CLI reference

The command-line tool is called awf.

The execution-mode facet belongs to the v0.3.0 candidate and requires a source build until that version clears its recorded publication gates.

It reads the bundled catalog and writes only inside the detected or explicit project root.

Run awf without arguments for actionable help, or run awf <command> --help for every option accepted by one command.

Use the global --project-root <directory> option when auto-detection should not select an initialized AWF project, Git repository, or package root.

Exit codes

Code	Meaning	Representative cases
0	The command completed normally.	Help, an empty filtered list, no installed workflows, a healthy status, or diagnostics containing warnings but no failures.
1	The command completed with an unhealthy report or encountered an operational or validation failure.	Drifted or invalid installations, failed doctor checks, unsafe paths, conflicts, missing workflows, or strict validation issues.
2	The command line is malformed or combines incompatible modes.	Unknown options, missing arguments, invalid option values, a status filter without --agent, or --show-content without --dry-run.
130	SIGINT requested safe cancellation on POSIX systems.	Usually produced by Ctrl+C.
143	SIGTERM requested safe cancellation on POSIX systems.	Usually produced by a process supervisor.

awf status --json and awf doctor --json are report commands.

When either command completes its inspection but finds an unhealthy state, it writes a valid versioned report to stdout, leaves stderr empty, and exits with code 1.

Warnings alone do not make doctor fail.

Other failed JSON operations write one versioned error object to stderr and leave stdout empty.

Automation should inspect both the exit code and the documented stream before choosing the corresponding output schema.

Windows forced termination does not expose the same portable POSIX signal result.

The Windows acceptance contract therefore verifies filesystem safety by terminating guided initialization before selection and asserting that no partial configuration exists.

awf context

Explain which project root the invocation selected without changing any file.

Human output includes the root, selection source, whether current-directory fallback occurred, and the reason.

Use --json for stable schema_version, project_root, selection_source, project_root_fallback, and reason fields.

This command is the recommended preflight when a script or nested workspace must audit root selection before another command runs.

Auto-detection uses the following precedence:

Order	Boundary	Behavior
1	--project-root <directory>	An explicit real directory always wins.
2	Nearest AWF configuration or Git marker	The CLI walks upward and stops at the first directory containing either boundary; .agentic-workflows/config.yml wins when both exist in that directory.
3	Nearest package.json	A package root is used only when no AWF configuration or Git marker encloses the invocation.
4	Invocation directory	The current directory is the explicit fallback when no marker exists.

An initialized nested project therefore remains independent inside a larger Git monorepo.

Use awf context --json before automation or pass --project-root when the caller must make that choice explicit.

awf list

Print the catalog.

Human output includes each workflow's execution mode beside its ID and summary so autonomous designs remain visible even without a filter.

Narrow the list with --category, --execution-mode, --agent, --tag, --adapter-status, --compatibility, --installation, --execution, and --outcome.

Use --json for complete machine-readable catalog records.

An empty human result explains how to clear the filters, while an empty JSON result remains [].

--adapter-status asks about an agent exporter as a whole, while --compatibility asks whether one recipe can be exported for that agent.

Any status filter that depends on an agent requires --agent.

Combined filters narrow the list together.

--execution-mode autonomous selects workflows designed to continue without mid-run human input after upfront authorization.

--execution-mode describes workflow design, while --execution filters retained evidence that a selected external agent actually ran the workflow.

Installation, execution, and outcome are independent evidence stages, so filtering on one says nothing about the others.

awf show <workflow-id>

Print the workflow identity, domain category, execution mode, difficulty, duration, tags, inputs, outputs, approvals, effects, and agent compatibility in human mode.

Use --agent to focus compatibility details and limitations on one destination.

Use --raw for the canonical workflow Markdown or --json for complete structured recipe metadata.

Use --location to print the version-matched local catalog page without launching another process.

The source checkout reads the tracked page under docs/catalog, and pnpm build copies the same page into the npm package.

The public catalog URL remains a fallback only when neither local source nor packaged documentation is available.

Use --open to open that local page with the operating system's native document handler.

Combine --open --json to receive schema_version, target, and opened without parsing presentation text.

The CLI waits for the native opener selected for Linux, macOS, or Windows to report success.

If the opener is missing or exits unsuccessfully, the command prints the exact path or URL to open manually instead of claiming success.

--raw, --location, and the recipe form of --json are mutually exclusive, while --open may be combined only with --json for its structured operation result.

An unknown workflow ID reports nearby IDs when a reliable match exists.

awf install <workflow-id>

Generate and copy a complete workflow bundle into a project.

--agent selects the destination format, and --target selects a project-root-relative directory inside the root reported by awf context.

--dry-run prints create, replace, unchanged, retire, modified, and missing file sets without changing the target.

Add --show-content to an install dry run to print the complete proposed generated files.

The dry-run JSON result retains the installation manifest fields and adds a versioned plan object.

--show-content without --dry-run is rejected because content preview is not an installation mode.

--json prints the applied installation manifest instead of human guidance.

--force replaces an existing managed installation of the same workflow after integrity checks.

It never permits overwriting an unmanaged file.

The install is transactional, so the entrypoint, checklist, complete examples, metadata, output schema, policy file when required, and manifest land together or not at all.

The hash-bearing manifest under .agentic-workflows/installations/ lets later updates and removals distinguish managed files from local edits.

After installation, the human output includes the invocation policy and exact command when the adapter defines one.

Installing files does not execute a workflow, approve its declared effects, or prove outcome quality.

awf update <workflow-id>

Rebuild an installed bundle using the adapter recorded at installation time.

--dry-run prints create, replace, unchanged, retire, modified, and missing file sets without changing the target.

Files whose generated content and retained hash are identical appear under unchanged and are not rewritten.

Add --show-content to print the complete proposed generated files after the human plan or inside the JSON plan.

Files changed locally are preserved unless --force explicitly authorizes replacing managed files.

An unmanaged destination remains protected even with --force.

Use --json for the structured update plan or resulting manifest.

awf remove <workflow-id>

Delete the files recorded in the installation manifest and then remove that manifest.

--dry-run lists every file that would be removed, including modified and missing managed files, without changing the target.

Locally modified managed files are preserved unless --force explicitly authorizes their removal.

Use --json to retain the removed manifest in machine-readable output.

awf status [workflow-id]

Inspect all local installation manifests or one selected workflow without changing files.

Human output reports the agent, recipe version, file count, and a health state of healthy, drifted, or invalid.

Drift details identify each modified or missing managed file.

Use --target to inspect another project-local target.

Use --json for a report with schema_version, target, project_context, filter, summary, and installations fields.

project_context contains project_root, selection_source, project_root_fallback, and reason, matching the root-selection evidence exposed by awf context --json.

Use --failures-only to keep complete healthy, drifted, and invalid summary counts while returning only drifted or invalid installation records.

The command exits with code 1 when any selected installation is drifted or invalid.

Selecting a workflow that is not installed returns NOT_FOUND with a preview command instead of an empty report.

awf validate [path]

Check a catalog, one recipe, an installation manifest, or an installation target.

Add --strict to run editorial content checks for recipes and installed-file hash checks for targets.

Use --json for a structured success result or a structured error with issue codes, paths, and remediation.

awf doctor

Run consumer health checks for Node compatibility, configuration, project root, target write access, catalog integrity, generated artifacts, installation integrity, lifecycle locks, and known agent commands.

The diagnostic also inspects .agentic-workflows/transactions for staged lifecycle state left by an abnormal process exit.

The target write check creates a unique temporary probe and removes it immediately.

Missing Corepack or pnpm is a warning for npm package consumers.

Use --maintainer to treat those source-development tools as required.

Use --failures-only to retain the full pass, warning, and failure summary while omitting passing check records from human and JSON output.

JSON diagnostics include projectContext with the selected root, stable source, and human-readable reason.

Failed and warning checks may include remediation and structured data, including a sanitized lifecycle-lock owner without its ownership token.

Every check has schema_version, check, status, detail, remediation, and data fields, with nullable values retained instead of omitted.

The top-level status, healthy, and exit_code fields provide the same verdict in string, boolean, and process-oriented forms.

The CLI never removes a lock automatically; confirm that the recorded process is inactive and the timestamp is stale before manual removal.

Human lifecycle-conflict errors show the sanitized PID and acquisition time, then direct the user to verify both before removing the lock and rerunning awf doctor.

The CLI also never removes staged transaction state automatically.

If lifecycle-transactions fails, first confirm that no lifecycle process owns the target and preserve any state needed for recovery.

Then run awf status and awf validate <target> --strict, reconcile managed files, remove only transaction directories proven abandoned, and rerun awf doctor.

Finding an agent command on PATH does not establish workflow execution or outcome evidence.

awf init

Create .agentic-workflows/config.yml with a default agent and target.

Running bare awf init in an interactive terminal starts a short agent and target wizard.

Use awf init --wizard to request that guided flow explicitly when standard input is redirected or a host cannot report an interactive terminal.

Non-interactive execution keeps deterministic defaults of generic and ., and providing --agent, --target, or --no-interactive skips the wizard.

--wizard is intentionally incompatible with --json, --no-interactive, --agent, and --target, while --force remains available for an explicitly reviewed configuration replacement.

--json also skips the wizard and returns a versioned result with the selected project context, configuration path, defaults, and whether an existing file was replaced.

Use --agent and --target to choose those defaults.

An existing configuration is never replaced unless --force is explicit.

An unsupported configuration schema fails with the detected version, supported versions, and an explicit recreation command.

An unsupported agent value fails during argument parsing, while an absolute, traversing, or symbolic-link target fails with INVALID_PATH before the configuration is replaced.

Back up values that must be retained before running awf init --force --no-interactive --agent <agent> --target <directory> because recreation replaces the configuration instead of guessing a migration.

When no Git, AWF configuration, or package marker exists, human project commands report that the current directory was selected and suggest --project-root.

JSON commands stay machine-only and do not emit that notice.

awf manifest <workflow-id>

Inspect and validate an installed workflow manifest.

Use --target to select another project-local target and --json to print JSON instead of YAML.

awf completion <shell>

Generate deterministic tab completion for bash, zsh, fish, or PowerShell (pwsh).

Add --install-instructions to print the exact persistent profile setup for the selected shell.

The instruction mode does not modify the profile or any path outside the project.

The generated script includes commands, options, agents, shell names, and the workflow IDs bundled with the installed CLI version.

Options are scoped to their commands, and list also completes categories, execution modes, tags, adapter support, compatibility, and installation, execution, and outcome states.

The CI matrix loads generated Bash, Zsh, Fish, and PowerShell scripts in their native shells and verifies returned candidates.

The command performs no network access and can be regenerated after upgrading the package.

Output and error contract

Human-readable output contains no terminal control sequences and remains plain when NO_COLOR is set.

Human errors preserve the stable error code and include structured issue remediation when available.

With --json, successful commands print exactly one JSON value to stdout and no decorative text.

With --json, failures print exactly one object to stderr and leave stdout empty.

Every JSON error contains error, message, a stable code, command, retryable, help_url, and remediation, and includes details for structured diagnostics and offline help.

details.help_command provides an offline command-specific reference, while help_url points to the matching published section.

On POSIX systems, SIGINT and SIGTERM use exit codes 130 and 143 after safe cancellation.

When --json is active, interruption emits one INTERRUPTED error object to stderr and leaves stdout empty.

The @kauanpolydoro/agentic-workflows/output-contract export provides executable Zod schemas and parseCliOutput for every machine-readable result, including catalog recipes and installation manifests whose canonical schemas remain owned by core.

See the CLI output contracts for the schema owner and compatibility rules of every JSON mode.