Praxa CLI Commands: Flags, Env Vars, and Usage Examples

This page covers every command available in @praxa/cli@0.3.0. Each section includes a description of what the command does, the full flag set, which environment variables it reads, and a runnable example. Gateway commands (doctor and mission), version, and memory planning write JSON to stdout. praxa init requires --json for JSON output, help output is text, and errors are written to stderr with exit code 1 on failure. For doctor and mission commands, the gateway URL resolves from --base-url, then PRAXA_BASE_URL (or legacy AURA_BASE_URL), then .praxa/config.json in the current working directory. PRAXA_ACCESS_TOKEN remains an environment-only secret.

`praxa version`

Prints the CLI version, the embedded OpenAPI spec version, the wire contract version, and a SHA-256 fingerprint of the OpenAPI source. This command makes no network connection and requires no configuration, making it a reliable smoke test after installation. Syntax

praxa version
# or
praxa --version

Flags This command accepts no flags. Environment variables None required. Example output

{
  "cliVersion": "0.3.0",
  "openapiVersion": "8.1.0",
  "contractVersion": "aura-integration-gateway-v8.1",
  "openapiSha256": "a9835faa4654246f83c452ae968a569c85be28f93017882e710ca35c10dbbecc"
}

Run praxa version immediately after installation to confirm the correct build is on your PATH and to capture the exact OpenAPI version for support requests.

`praxa init`

Configures one or more project-scoped agent clients without writing an access token into project files. Syntax

praxa init [--base-url <url>] [--target <target>] [--auth environment|oauth] \
  [--project-dir <path>] [--dry-run] [--force] [--json]

Use --target repeatedly to select codex, claude, cursor, vscode, or env; omit it to configure all targets. --dry-run reports intended changes without writing files, and --force replaces a conflicting managed entry.

praxa init --target codex --target cursor --project-dir . --json

`praxa memory source add`

Previews or writes one read-only memory-provider entry in .praxa/memory.json. The command accepts no provider credential and makes no provider or gateway request. Syntax

praxa memory source add <provider> --mode federated \
  [--project-dir <path>] [--dry-run] [--json]

<provider> must be mem0, zep, graphiti, langgraph, letta, or openai_agents. --mode federated is required. Use --dry-run to return the exact local file plan without writing.

npx --package=@praxa/cli@0.3.0 praxa memory source add mem0 \
  --mode federated --dry-run

The result identifies the project directory, .praxa/memory.json action, provider, read-only access, and local-only execution boundary. It never reports a provider connection or sync.

`praxa memory sync plan`

Reads local source metadata and returns a bounded, non-executable plan. It cannot start a sync, mirror, import, cutover, provider write, or migration. Syntax

praxa memory sync plan --dry-run [--project-dir <path>] [--json]

npx --package=@praxa/cli@0.3.0 praxa memory sync plan --dry-run

--dry-run is required. The returned executable field is always false and operations is empty in 0.3.0.

`praxa doctor`

Makes an authenticated read-only request to your gateway to verify that the URL is reachable, the TLS certificate is valid, and the access token is accepted. It fetches reference coverage data and returns it alongside an ok: true field on success. Syntax

praxa doctor [--base-url <url>]

Flags

Flag	Description
`--base-url <url>`	Gateway HTTPS URL. Overrides environment variables and `.praxa/config.json`.

Environment variables

Variable	Description
`PRAXA_BASE_URL`	Gateway HTTPS URL; overrides `.praxa/config.json` when no flag is present
`PRAXA_ACCESS_TOKEN`	Short-lived delegated OAuth token (required)

Example

praxa doctor

{
  "ok": true,
  "coverage": { ... }
}

`praxa mission submit`

Records natural-language intent for deterministic compilation. A successful response is durable admission, not proof of execution or a provider outcome. Syntax

praxa mission submit --intent <text> --idempotency-key <key> [--base-url <url>]

Flag	Required	Description
`--intent <text>`	Yes	Natural-language intent between 1 and 4,000 characters
`--idempotency-key <key>`	Yes	A stable 16–128 character key for this logical submission
`--base-url <url>`	No	Gateway HTTPS URL. Overrides environment variables and `.praxa/config.json`.

praxa mission submit \
  --intent "Prepare a governed deployment plan" \
  --idempotency-key $(uuidgen)

`praxa mission get`

Retrieves an authoritative mission projection for the given run ID. Use this command to poll mission status, inspect the current state, or retrieve output after a mission completes. Syntax

praxa mission get --run-id <uuid> [--base-url <url>]

Flags

Flag	Required	Description
`--run-id <uuid>`	Yes	The UUID of the mission run to retrieve
`--base-url <url>`	No	Gateway HTTPS URL. Overrides environment variables and `.praxa/config.json`.

Environment variables

Variable	Description
`PRAXA_BASE_URL`	Gateway HTTPS URL; overrides `.praxa/config.json` when no flag is present
`PRAXA_ACCESS_TOKEN`	Short-lived delegated OAuth token (required)

Example

praxa mission get --run-id 550e8400-e29b-41d4-a716-446655440000

You can pipe the output to jq to extract a specific field:

praxa mission get --run-id 550e8400-e29b-41d4-a716-446655440000 | jq '.status'

`praxa mission create`

Submits a new mission to the Praxa Integration Gateway by reading a JSON file from disk. The response contains the assigned run ID and the initial mission state. Syntax

praxa mission create --input <path> --idempotency-key <key> [--base-url <url>]

Flags

Flag	Required	Description
`--input <path>`	Yes	Path to a JSON file containing the mission payload
`--idempotency-key <key>`	Yes	One stable 16–128 character key for this logical mission; reuse it for retries
`--base-url <url>`	No	Gateway HTTPS URL. Overrides environment variables and `.praxa/config.json`.

Environment variables

Variable	Description
`PRAXA_BASE_URL`	Gateway HTTPS URL; overrides `.praxa/config.json` when no flag is present
`PRAXA_ACCESS_TOKEN`	Short-lived delegated OAuth token (required)

Mission file format Your --input file must be valid JSON with at minimum a goalSpec object and a resourceBudget object:

{
  "goalSpec": { "task": "Prepare the weekly review" },
  "resourceBudget": {
    "maximumSteps": 12,
    "maximumToolCalls": 8,
    "maximumElapsedMs": 120000,
    "maximumParallelism": 2
  }
}

Example

praxa mission create \
  --input mission.json \
  --idempotency-key $(uuidgen)

Store the returned run ID for subsequent get or cancel calls:

RUN_ID=$(praxa mission create \
  --input mission.json \
  --idempotency-key $(uuidgen) | jq -r '.runId')

echo "Mission started: $RUN_ID"

`praxa mission cancel`

Requests durable cancellation of a running mission. The reason string is recorded in the mission audit log. Create one stable idempotency key for this logical cancellation and reuse it if a network failure requires a retry. Syntax

praxa mission cancel \
  --run-id <uuid> \
  --reason <text> \
  --idempotency-key <key> \
  [--base-url <url>]

Flags

Flag	Required	Description
`--run-id <uuid>`	Yes	The UUID of the mission run to cancel
`--reason <text>`	Yes	Human-readable cancellation reason recorded in the audit log
`--idempotency-key <key>`	Yes	One stable 16–128 character key for this logical cancellation; reuse it for retries
`--base-url <url>`	No	Gateway HTTPS URL. Overrides environment variables and `.praxa/config.json`.

Environment variables

Variable	Description
`PRAXA_BASE_URL`	Gateway HTTPS URL; overrides `.praxa/config.json` when no flag is present
`PRAXA_ACCESS_TOKEN`	Short-lived delegated OAuth token (required)

Example

praxa mission cancel \
  --run-id 550e8400-e29b-41d4-a716-446655440000 \
  --reason "User requested cancellation" \
  --idempotency-key $(uuidgen)

Gateway commands (doctor and mission), version, and memory planning write pretty-printed JSON to stdout, making them easy to pipe to jq. Pass --json to praxa init when you need machine-readable output; help remains human-readable text. Errors are written to stderr and the process exits with code 1.

Idempotency keys must contain 16–128 supported characters and match ^[A-Za-z0-9][A-Za-z0-9._:-]{15,127}$. Create one key per logical mutation and reuse it for every retry of that same mutation. A value from $(uuidgen) is valid, but UUIDs are not required. Never reuse a key for a different mutation because the gateway binds the key to the original request.

Workflows

Automate and operate

Praxa CLI Commands: Flags, Env Vars, and Usage Examples

`praxa version`

`praxa init`

`praxa memory source add`

`praxa memory sync plan`

`praxa doctor`

`praxa mission submit`

`praxa mission get`

`praxa mission create`

`praxa mission cancel`

​praxa version

​praxa init

​praxa memory source add

​praxa memory sync plan

​praxa doctor

​praxa mission submit

​praxa mission get

​praxa mission create

​praxa mission cancel

`praxa version`

`praxa init`

`praxa memory source add`

`praxa memory sync plan`

`praxa doctor`

`praxa mission submit`

`praxa mission get`

`praxa mission create`

`praxa mission cancel`