Praxa CLI: Manage Agent Missions from the Terminal

@praxa/cli is a thin command-line adapter over @praxa/sdk. It submits, inspects, and cancels Praxa missions through your Integration Gateway, and it can plan read-only memory federation metadata locally. The CLI never stores provider credentials or calls AI providers directly.

Install and verify

Pin 0.3.0, select the explicit praxa bin, verify the contract, and run a read-only diagnostic.

Configure a project

Set up Codex, Claude Code, Cursor, VS Code, or environment-only clients without writing a token.

Automate with JSON

Use strict exits, stable keys, redacted CI logs, and deliberate cleanup.

Installation

Install the CLI globally to make the praxa binary available everywhere on your system, or run it on demand with npx if you prefer not to install it.

npm install --global @praxa/cli
# or use without installing
npx --package=@praxa/cli@0.3.0 praxa mission submit --intent "Prepare a governed deployment plan" --idempotency-key $(uuidgen)

Configuration

Gateway commands (praxa doctor and praxa mission …) require the URL of your Praxa Integration Gateway and a valid OAuth access token. The gateway URL resolves in this order: --base-url, PRAXA_BASE_URL (or the legacy AURA_BASE_URL), then .praxa/config.json in the current project. praxa version, praxa init, and the local praxa memory planning commands do not require a gateway connection or provider credential.

Variable	Required for gateway commands	Description
`PRAXA_BASE_URL`	When no flag or project config supplies it	The HTTPS base URL of your Praxa Integration Gateway, e.g. `https://api.example.com`
`PRAXA_ACCESS_TOKEN`	Yes	A short-lived delegated OAuth token scoped to the operations you need

The --base-url flag overrides the environment and .praxa/config.json for one invocation. An environment URL overrides project config. This is useful when targeting a staging gateway without changing the initialized project.

The CLI validates that PRAXA_BASE_URL (and --base-url) use the https: protocol and contain no embedded credentials. Plain HTTP URLs and https://user:pass@… URLs are rejected at startup.

A typical .env file looks like this:

# .env
PRAXA_BASE_URL="https://api.example.com"
PRAXA_ACCESS_TOKEN="<short-lived delegated OAuth token>"

Never place a provider API key in PRAXA_BASE_URL or PRAXA_ACCESS_TOKEN. These variables must only contain your gateway URL and a delegated Praxa OAuth token respectively.

Available Commands

Command	Description
`praxa version`	Prints CLI, OpenAPI spec, and contract version info — no network call required
`praxa init`	Configures a project-scoped client without writing an access token
`praxa memory source add <provider> --mode federated [--dry-run]`	Previews or writes read-only local source metadata
`praxa memory sync plan --dry-run`	Inspects a non-executable local federation plan
`praxa doctor`	Performs an authenticated read-only health check against your gateway
`praxa mission submit`	Records natural-language intent for deterministic compilation
`praxa mission get`	Fetches a mission by its run ID
`praxa mission create`	Submits a new mission from a JSON file
`praxa mission cancel`	Cancels a running mission

Gateway commands (doctor and mission), version, and memory planning write JSON to stdout. praxa init writes human-readable output unless you pass --json, and help output is text. Memory planning implements no provider connection, synchronization, import, mirror, or cutover operation.

Command Reference

Full flag tables, environment variables, and example output for every command

Test the CLI and package release

Install the public release in a clean project, assert exact versions, run dry-run memory planning, and separate package proof from live Gateway proof.

Workflow handbook

Goal	Guide
Install and prove the public artifact	Getting started
Initialize host configuration	Project setup
Submit, inspect, replay, and cancel missions	Mission workflows
Plan read-only memory federation	Memory workflows
Script and run in CI	Automation and JSON
Apply safe operating defaults	Best practices
Look up every flag	Command reference
Diagnose a failure	CLI troubleshooting

Workflows

Automate and operate

Praxa CLI: Manage Agent Missions from the Terminal

Install and verify

Configure a project

Automate with JSON

Installation

Configuration

Available Commands

Command Reference

Test the CLI and package release

Workflow handbook

Install and verify

Configure a project

Automate with JSON

​Installation

​Configuration

​Available Commands

Command Reference

Test the CLI and package release

​Workflow handbook

Installation

Configuration

Available Commands

Workflow handbook