Praxa CLI best practices

​

Installation and invocation

• Pin @praxa/cli@0.3.0 in automated workflows.
• Use the explicit praxa executable with one-off npx commands because the package also exposes the legacy aura bin.
• Run praxa version and assert the OpenAPI fingerprint before networked work.
• Prefer a project development dependency for repeatable team automation.
• Keep global installs for interactive convenience, not release authority.

npx --package=@praxa/cli@0.3.0 praxa version

​

Preview before mutation

npx --package=@praxa/cli@0.3.0 praxa init \
  --project-dir . \
  --target codex \
  --auth environment \
  --dry-run \
  --json

​

Credential handling

• Supply PRAXA_ACCESS_TOKEN only at runtime.
• Use a short-lived delegated Gateway OAuth token, never an Execution Fabric API key or provider key.
• Keep .praxa/config.json limited to non-secret project metadata and Gateway origin.
• Mask environment values in CI and disable shell tracing around secrets.
• Remove tokens from child-process environments that do not need them.
• Revoke disposable credentials after live tests.

​

Stable mission identity

praxa mission create \
  --file mission.json \
  --idempotency-key "$LOGICAL_MISSION_KEY"

​

Shell and CI behavior

set -euo pipefail

output="$(praxa doctor)"
printf '%s\n' "$output" | jq -e '.ok == true' >/dev/null

• Check the process exit before parsing stdout.
• Capture stderr separately and redact it before artifact upload.
• Use --json where the command supports it; help and default init output are human text.
• Validate required JSON fields with jq -e or a typed parser.
• Set an outer job timeout; do not assume the command owns the complete pipeline deadline.
• Serialize operations that share one logical idempotency record.

​

Failure and reconciliation

​

Team operations

• Document which environment owns each Gateway URL.
• Keep production invocations in reviewed scripts, not copied shell history.
• Require peer review for mission JSON that changes budgets or committing tool authority.
• Store redacted run IDs and outcomes as deployment evidence.
• Test missing, expired, revoked, and under-scoped tokens in staging.
• Include a rollback path to the prior pinned CLI package.

​

Upgrade checklist

1. Install the new CLI and SDK in a clean temporary project.
2. Compare praxa version with the approved contract values.
3. Run init --dry-run --json and memory planning; require no unexpected write.
4. Review help and command-reference changes.
5. Run a read-only doctor against staging.
6. Exercise one disposable mission with replay and terminal readback.
7. Update the project lock and automation image only after those checks pass.