DevProjex Command Line

DevProjex Desktop, Terminal, and CLI follow the same inspect -> select -> verify -> export product workflow. Terminal Workspace and direct CLI share terminal planning and document services; Desktop keeps its established presentation and export orchestration. They are not one interchangeable implementation pipeline.

The portable distribution contains one primary executable per RID: DevProjex.exe on Windows and DevProjex on Linux and macOS.

Getting Started

After enabling Help > Launch from terminal:

devprojex --help
devprojex
devprojex analyze .
devprojex export context . -o ../devprojex-context.md
devprojex open . --preview

devprojex opens the interactive Terminal Workspace when stdin and stdout are interactive. With redirected streams it prints plain root help and exits. A desktop shortcut or direct launch without an attached terminal opens Avalonia.

The executable name is shown as devprojex throughout this document. Portable users should install or generate the platform launcher and use that command. Direct invocation of the physical Windows WinExe path is an advanced diagnostic detail and is not the supported shell entry point.

Command Tree

devprojex
├── tui
├── open
├── analyze
├── export
│   ├── context
│   └── project
├── profile
│   ├── show
│   ├── export
│   ├── import
│   ├── validate
│   └── reset
├── ui
│   ├── list
│   ├── status
│   ├── activate
│   ├── preview
│   ├── tree
│   ├── filter
│   └── search
├── doctor
├── completion
└── dev
    ├── benchmark
    │   ├── analysis
    │   └── ui
    └── session

dev is a hidden maintainer namespace. See CONTRIBUTING.md for its supported diagnostic workflows.

Commands, option names, enum tokens, JSON properties, and XML element names are stable English identifiers. --language CODE localizes human-readable help, status, diagnostics, and Terminal Workspace labels.

Common Selection Options

analyze, export context, export project, and open accept the same typed selection. open additionally accepts auto:

--profile <standard|local|FILE>
--root <PATH>                 repeatable
--extension <EXT>            repeatable
--select <RELATIVE_PATH>     repeatable
--git-mode <none|gitignore|tracked>
--exclude <NAME>             repeatable

For open, the first line is --profile <auto|standard|local|FILE> and its default is auto. Direct analyze/export commands default to standard.

Git filtering is independent from ordinary Exclusions.

Git modes:

Token	Behavior
none	No Git-based filtering
gitignore	Respect applicable hierarchical .gitignore rules
tracked	Include only paths returned from applicable indexes by the installed Git CLI; no readable index fails closed with exit 3

A readable empty index is a valid tracked view with zero files. If at least one index loads but a nested index does not, that nested scope is excluded and reported with DPX-GIT-TRACKED-INDEX-PARTIAL. If none load, commands report DPX-GIT-TRACKED-INDEX-UNAVAILABLE; they never reinterpret tracked as gitignore. An absent .gitignore is an active empty rule set, not a fallback to none. The administrative path named exactly .git remains excluded; .github and other .git* names are not treated as Git metadata.

Exclusion tokens:

smart-ignore
hidden-folders
hidden-files
dot-folders
dot-files
empty-folders
empty-files
extensionless-files
none

If at least one --exclude is present, the supplied values are the exact ordinary exclusion set. --exclude none selects an empty set and cannot be combined with another exclusion. If an option is absent, its value comes from the selected profile.

Modern local profiles retain checked and unchecked states across roots, extensions, and Exclusions. Newly discovered rows use current defaults in Desktop, CLI, and TUI; explicit CLI collections remain exact and invocation-only.

Selected paths are relative to the project root. A file selects that file; a directory selects its effective subtree. Parent/child overlaps are deduplicated. An empty selected-path set means the complete effective tree. Absolute paths, .., and link-based escapes are rejected.

Terminal Workspace

devprojex
devprojex tui [PROJECT]

Options:

--profile <auto|standard|local|FILE>
--screen <auto|alternate|inline>
--mouse
--no-mouse
--color <auto|always|never>
--plain
--language <CODE>

The TUI default auto profile uses the local project profile when one exists, otherwise the standard profile. It provides recent local and Git workspaces, a lazy project tree, readable and exact Raw Preview, Context Controls, a searchable Action Palette, selection, search, roots, extensions, Git filtering, Exclusions, metrics, profiles, and context/folder/ZIP export. See TerminalWorkspace.md.

Open Desktop

devprojex open [PROJECT] [options]

Useful options:

--last
--new-window
--wait
--preview
--view <tree|content|tree-content>
--tree-format <text|markdown|json|xml>
--filter <QUERY>
--search <QUERY>

PROJECT defaults to the current directory. --last cannot be combined with a project argument or selection/profile overrides. --filter and --search are mutually exclusive. --view and --search imply --preview.

Without --new-window, DevProjex reuses a suitable desktop instance through local per-user IPC. The default returns after the desktop accepts the request; --wait waits until the requested project and state are applied.

Examples:

devprojex open .
devprojex open . --preview --view tree-content
devprojex open . --search "Program"
devprojex open --last

Analyze

devprojex analyze [PROJECT] [options]

Defaults:

• project: current directory;
• format: text;
• output: stdout;
• profile: standard.

Specific options:

--format <text|json>
-o, --output <PATH|->
--strict
--color <auto|always|never>
--progress <auto|always|never>
--verbosity <quiet|minimal|normal|detailed|diagnostic>
--plain

Text is a human-readable project summary. JSON is a stable machine document with schemaVersion. --strict still writes the report, then returns exit code 3 when policy diagnostics exist. Analysis is already read-only and therefore has no --dry-run option. A file destination must be outside the source project and must not already exist. Its parent directory must already exist.

Examples:

devprojex analyze .
devprojex analyze . --format json -o -
devprojex analyze ./app --format json -o report.json --strict
devprojex analyze . --git-mode tracked --exclude smart-ignore

Export Context

devprojex export context [PROJECT] [options]

Defaults:

• view: tree-content;
• format: markdown;
• output: stdout;
• profile: standard.

Specific options:

--view <tree|content|tree-content>
--format <text|markdown|json|xml>
-o, --output <PATH|->
--force
--dry-run

The format applies to the entire document. JSON and XML are parseable structured documents; Markdown contains headings, a fenced tree, and fenced text-file content. Binary bytes are never embedded in context output. Machine documents mark binary entries with metadata.

When output is stdout, stdout contains only the context document. When output is a file, stdout contains one absolute result path. Existing files are conflicts unless --force is used; replacement is atomic. The destination parent directory must already exist.

--force is valid only for a file destination, never for stdout. --dry-run performs planning and destination preflight but does not generate a document, create an artifact, or print a result path. Its operational plan is written to stderr.

Examples:

devprojex export context .
devprojex export context . --view tree --format json -o -
devprojex export context . --view content --format xml -o ../devprojex-context.xml
devprojex export context . --format markdown -o ../devprojex-context.md --force

Export Project

devprojex export project [PROJECT] --as <folder|zip> -o <PATH> [options]

The destination is exact:

devprojex export project . --as folder -o ../devprojex-submission
devprojex export project . --as zip -o ../devprojex-submission.zip

The first command creates exactly ../devprojex-submission; it does not create an additional project-name child or (2) suffix. The folder must not exist. A ZIP path must end in .zip and must not exist unless --force is supplied. --force is not valid for folder exports. In both cases the destination parent directory must already exist.

Folder and ZIP exports preserve selected binary bytes, timestamps, directory structure, and included empty directories. Staging is cleaned after cancellation or failure. Canonical destination checks reject destinations equal to or inside the source, including paths reached through symlinks or junctions.

On success stdout contains exactly one absolute result path. Measured progress and warnings use stderr.

Profiles

devprojex profile show [PROJECT] [--profile standard|local|FILE] [--format text|json]
devprojex profile export [PROJECT] [--profile standard|local|FILE] -o FILE [--force]
devprojex profile import FILE [PROJECT] [--apply]
devprojex profile validate FILE
devprojex profile reset [PROJECT]

Direct commands default to standard. Terminal Workspace uses local when available, then standard. Explicit CLI selection options override profile fields. See CLI-Profiles.md.

Portable profile output must resolve outside the source project, including filesystem aliases, and its parent directory must already exist. Source safety is validated before conflicts. An existing file requires --force for atomic replacement; an existing directory is always a destination conflict. On success stdout contains one absolute committed path. Errors and diagnostics use stderr.

Desktop Control

devprojex ui list [--format text|json]
devprojex ui status
devprojex ui activate
devprojex ui preview open [--view tree|content|tree-content]
devprojex ui preview close
devprojex ui preview set-view <tree|content|tree-content>
devprojex ui tree set-format <text|markdown|json|xml>
devprojex ui filter set <QUERY>
devprojex ui filter clear
devprojex ui search set <QUERY>
devprojex ui search next
devprojex ui search previous
devprojex ui search clear

Targetable actions accept:

--instance <ID>
--project <PATH>
--timeout <DURATION>

IPC is local-only and per-user. It exposes semantic actions, not arbitrary method invocation. See Desktop-Control.md.

Doctor

devprojex doctor
devprojex doctor --format json

Doctor inspects version/runtime, package type, terminal capabilities, launcher and PATH resolution, Git, current directory, profile/data/cache/temp access, desktop IPC registrations, and tracked-mode readiness. It reports fixes as hints but does not change the system. Desktop IPC is reported as skipped until a Desktop session initializes it; an existing inaccessible or path-conflicted registry is a failure.

Completion

Completion scripts are generated from the same command tree:

devprojex completion bash
devprojex completion zsh
devprojex completion fish
devprojex completion powershell

The generated script queries the production command tree using the current command line and cursor position. Suggestions are scoped to the active command, option values, repeatability, conflicts, and path arguments. It does not execute Avalonia or require another DevProjex executable. Evaluate or install it using the shell's normal completion mechanism.

Streams and Exit Codes

stdout is reserved for payloads, one result path, help/version, and completion. Progress, warnings, diagnostics, migration guidance, and errors use stderr. JSON and XML never contain ANSI, animation frames, or extra summary lines.

Code	Meaning
0	Success, help, or version
1	Runtime or I/O failure
2	Invalid syntax, option, value, or combination
3	Policy/check failure
4	Destination conflict
5	Desktop target unavailable or ambiguous
130	Canceled

Human errors include a stable DPX-* code. Normal output does not expose raw platform exception messages. See CLI-Output-Contract.md.

Legacy Syntax

The experimental flat CLI is no longer executed. A small set of unambiguous legacy action/value shapes returns exit code 2 and prints an exact replacement argument vector to stderr. Malformed, incomplete, duplicated, or unsupported legacy shapes do not receive a speculative replacement. See CLI-Migration.md.

More Detail

• CLI-V1-Contract.md: normative public contract
• CLI-Architecture.md: layers and one-EXE routing
• CLI-Output-Contract.md: streams and schemas
• CLI-Profiles.md: portable profiles and precedence
• Desktop-Control.md: local IPC
• TerminalWorkspace.md: interactive TUI