Proxima Agent CLI

proxima is the CLI for Proxima Skills, Plugins, conversation Widgets and optional MCP tools. It downloads and verifies capability bundles and installs them into Agent-visible directories. Hosted Widget commands use authenticated Session-local Runtime control without registering or invoking MCP.

Requirements and build

• Node.js 20 or newer
• A Proxima prx_ API Key with * or skills:read for Skills; MCP permissions are still enforced by the server

npm ci
npm run build
npm link
proxima --help

For a packaged release:

npm install -g @aido.ai/proxima

Configuration

The API Key is accepted only through an environment variable or a profile's apiKeyEnv reference. Do not put a raw Key on the command line.

export PROXIMA_API_KEY='prx_...'
export PROXIMA_URL='https://proxima.example.com'

proxima config show

With PROXIMA_URL, Registry and MCP endpoints are derived from the same origin:

https://proxima.example.com/api/v1
https://proxima.example.com/mcp

They can be overridden independently with PROXIMA_REGISTRY_URL and PROXIMA_MCP_URL. Without any URL configuration, local defaults are http://localhost:8090/api/v1 and http://localhost:8080/mcp.

Optional profile file: ${XDG_CONFIG_HOME:-~/.config}/proxima/config.json.

{
  "defaultProfile": "work",
  "profiles": {
    "work": {
      "baseUrl": "https://proxima.example.com",
      "apiKeyEnv": "PROXIMA_WORK_API_KEY",
      "timeoutMs": 20000
    }
  }
}

Precedence is command flags, environment, selected profile, then defaults.

Resume a recorded Session

Resume creates a new local Codex or Claude Session from observable conversation context; it does not restore files, approvals, hidden reasoning or the exact original process state.

Use an owner-bound API Key with * or sessions:read scope and run from the intended workspace, or supply --cwd.

proxima resume <session-id> --agent codex --mode handoff --dry-run
proxima resume <session-id> --agent codex --mode handoff

If the source has unfinished requests, the server reports session_not_quiet until you explicitly acknowledge that current and future output may be missing:

proxima resume <session-id> --agent codex --mode handoff --allow-active

--allow-active confirms that only currently recorded context is imported, later messages are not added automatically, and the original Session continues independently; generic --yes does not replace this acknowledgement.

The Dashboard Resume drawer explains these limitations in a confirmation dialog before copying the command.

Real imports require a server supporting POST /api/v1/sessions/{id}/resume-snapshots; the server fixes the canonical snapshot before native materialization and returns a receipt valid for one hour, so source changes during import do not invalidate lineage registration.

--dry-run uses GET and does not persist a snapshot or write a native Session; active dry-runs still require --allow-active.

The CLI reports fidelity omissions and prints the native resume command after registration succeeds; run that printed command to continue locally.

Deploy the compatible API before releasing this CLI; old CLI versions retain their existing quiet-Session export behavior and do not recognize --allow-active.

Conversation Widgets

Widget commands require a compatible, explicitly enabled Proxima-hosted Agent Session and its uniquely active Run; installing the CLI alone does not enable server-side rendering. The Runtime supplies Session-local control credentials automatically, and no API Key or MCP server is needed for these commands.

proxima --json widget begin --title "Research report"

# Replace the example UUID with data.id from the begin receipt.
proxima widget render --id 11111111-1111-4111-8111-111111111111 --stdin <<'PROXIMA_WIDGET_HTML'
<style>body { font-family: system-ui; }</style>
<main><h1>Example report</h1><button id="details">Show details</button></main>
<script>document.querySelector('#details').onclick = () => { document.querySelector('#details').textContent = 'Details shown'; };</script>
PROXIMA_WIDGET_HTML

Use the exact quoted heredoc as a single native shell command for supported incremental previews; put meaningful HTML/CSS first and scripts last. File or pipe input can publish final content but does not guarantee progressive previews. Keep the delimiter out of standalone source lines and keep source within 512 KiB of UTF-8.

Previews are inert; scripts execute only after validated, durable final publication in the separate sandboxed renderer. Widgets do not expose a Host-action or Tool bridge, and external resources are denied by the renderer policy. Refresh/reset starts a new interaction state. Do not put credentials or secrets in generated source.

Skills

proxima skills search "github review"
proxima skills info acme/github-review
proxima skills info acme/[email protected]

# User-level Codex install under ~/.agents/skills
proxima skills install acme/[email protected] --agent codex --scope user

# Project install under .agents/skills
proxima skills install acme/[email protected] --agent codex --scope project

# Claude Code installs use ~/.claude/skills or .claude/skills
proxima skills install acme/[email protected] --agent claude-code --scope user
proxima skills install acme/[email protected] --agent claude-code --scope project

# Generic Agent target
proxima skills install acme/[email protected] \
  --agent generic --scope user --target-dir ./agent-skills

proxima skills update acme/github-review --agent codex --scope user
proxima skills list --scope user --agent codex
proxima skills remove acme/github-review --scope user --agent codex

Plugin commands support hosted installation receipts and explicit local Agent installations.

Without --agent and --scope, installation remains hosted:

proxima plugins search [query]
proxima plugins info namespace/name
proxima plugins list [--installed]
proxima plugins install namespace/name[@version] --connector <requirement-id>=<connection-id> --yes
proxima plugins remove namespace/name --yes

Use plugins info to inspect Connector requirement IDs, eligible Connection IDs, and governed runtime dependencies. A version suffix asserts the currently published version; it does not enable historical or yanked installs. Mutations prompt in a terminal and require --yes in automation.

To install the current published Plugin into a native Agent:

proxima plugins install proxima/docs-flow --agent codex --scope project --yes
proxima plugins install proxima/docs-flow --agent claude-code --scope project --yes
proxima plugins update proxima/docs-flow --agent codex --scope project --yes
proxima plugins list --agent codex --scope project
proxima plugins remove proxima/docs-flow --agent codex --scope project --yes
# Use --scope user for a user-level installation.

Both local options are required together; local commands never create a hosted installation receipt.

The consumer API accepts tenant-bound, user-owned prx_ keys with plugins:read for discovery/download, and plugins:write for hosted installation/removal; hosted CLI mutations also read state and therefore need both scopes (or *).

Older servers accepting only Dashboard JWTs return an authentication error; the new consumer API must be deployed before these commands work with API keys.

Local installation requires an online, published, security-passed Plugin without hosted Connector, Runtime dependency, native MCP/app, or Proxima UI requirements.

The CLI preserves the verified authoritative bundle content under <project-or-home>/.proxima/plugins/<agent>/, checks SHA-256 and native manifests, rejects unsafe archives, and records version/source/file ownership in .proxima-plugin.json.

The native Agent receives a separate activation copy; for Codex, the legacy manifest hooks field is omitted only for the conventional hooks/hooks.json path, whose bytes remain unchanged.

No bundle scripts or hooks run during installation, and native hook trust remains in force when an Agent later uses the Plugin.

Codex must already trust the project to activate its .codex/config.toml; the installer never changes project trust and never enables a project Plugin globally.

Codex uses an isolated native CLI installation to prepare its shared cache, then an owned configuration block for the requested scope; Claude Code uses its native scoped marketplace/install commands.

Both Agents may keep Plugin cache data in their normal user configuration directory even for project-scoped activation.

Installation/update verifies native activation before recording success; local listing reads Proxima's owned installation inventory offline, and removal requires matching unmodified source/cache ownership.

Updates preserve the original Registry source and native Agent configuration home and refuse modified files; failed native activation restores the prior installation where possible and explicitly reports any incomplete rollback.

Existing Plugins from other marketplaces are preserved, including a separately installed local docs-flow; replacing that installation is a separate exact-target native uninstall after the Proxima version is verified.

Start a new Agent thread after installing or updating to pick up the Plugin's instructions.

The Skill installer verifies the Registry SHA-256, archive paths, symlinks, duplicates, file/expanded-size limits and SKILL.md. It extracts to a staging directory and atomically switches the target. .proxima-skill.json and the user/project lockfile record ownership. Removal refuses an unowned target.

Skill locks use an Agent-qualified key, so the same exact Skill version can be installed for Codex and Claude Code without losing ownership metadata. Existing schema-v1 locks are read and upgraded on the next write. An existing same-Agent installation keeps its recorded target during updates, including legacy Codex targets. When a Skill is installed for more than one Agent, skills remove requires --agent.

Agent hooks

Agent hooks inject a capability router at session and subagent start. When configured credentials are available, generate/install resolve a tenant-assigned, platform-managed Policy Skill variant and materialize it locally. Without online configuration, they use the small embedded router and report that fallback in their JSON result.

# Generate reviewable files without changing native Agent configuration
proxima hooks generate --agent codex --scope project --out .proxima/generated-hooks/codex

# Atomically merge the owned hook while preserving unrelated settings
proxima hooks install --agent codex --scope project
proxima hooks install --agent claude-code --scope user

# Claude project hooks default to settings.local.json; opt into shared settings.json
proxima hooks install --agent claude-code --scope project --shared

proxima hooks doctor --agent codex --scope project
proxima hooks sync --agent codex --scope project
proxima hooks uninstall --agent codex --scope project

The installed runner is a local, fixed prompt emitter. It does not read transcripts, call a model, contact Proxima, or install Skills. A receipt records the installation ID, selected Policy source/version/variant, exact native config, and runner digest. hooks sync explicitly resolves the current assignment and atomically updates an unmodified owned runner; doctor checks local integrity and may report online freshness without changing files. Uninstall removes only Proxima-owned handlers and deletes the runner only when its digest still matches; a user-modified runner is preserved. Changing a Claude project hook between local and shared configuration requires uninstalling first.

Codex requires review/trust of new or changed non-managed hooks through /hooks. Claude Code user hooks are written to ~/.claude/settings.json; project hooks default to .claude/settings.local.json, or .claude/settings.json with --shared.

MCP

proxima mcp status
proxima mcp tools list
proxima mcp tools search github
proxima mcp tools search "github issue" --operation-class read --limit 20
proxima mcp tools list --connector github --cursor <next_cursor>
proxima mcp tools inspect github_work__list_issues
proxima mcp tools inspect github_work__list_issues --all-parameters --schema
proxima mcp tools call github_work__list_issues \
  --args-json '{"state":"open"}'

# Agent-friendly arguments and exact file content
proxima mcp tools call github_work__create_issue \
  repo=acme/demo title="Bug" [email protected] --yes

Use --args-file request.json or --args-file - for stdin. Tool arguments are checked against the advertised JSON Schema before sending.

mcp tools list pages through authorized Tools, while mcp tools search <query> performs bounded server-side search. Natural-language and multi-word queries are ranked by the server across Tool names, descriptions, Connector and Connection names, and input schemas; the CLI preserves that server ordering without applying its own relevance logic. skills search <query> likewise accepts natural-language queries and preserves the Registry's ranked order. Both search surfaces return next_cursor, and Tool results retain the MCP-compatible inputSchema, annotations, and _meta shape. inspect and call still use MCP and the server re-authorizes every invocation.

Unknown or mutating tools require local confirmation. In non-interactive environments, mutation requires --yes; this never bypasses server authorization or owner approval. Destructive tools are denied. If Proxima requires owner approval, the command returns exit code 9 with the approval ID, review URL, requester status Tool, and polling interval. Poll the advertised read-only status Tool, then retry the original call with --approval-id only after it reports approved.

For automatic waiting without adding each poll to an LLM conversation, run proxima --json mcp approvals wait <approval-id> once through the Agent's execution tool; use background execution and its completion notification when supported.

The process polls the requester-scoped status Tool every five seconds and writes no progress messages, producing one final JSON envelope when the status becomes approved, rejected, expired, or consumed.

Only data.status=approved permits an approval retry; successful command completion means the wait finished, not that the owner approved the operation.

Consumed approvals retain an available task_id and poll_tool handoff, and the waiter never approves, consumes, or executes a write.

--wait-timeout <seconds> sets the overall deadline (default 600 seconds, maximum 3600); --timeout <ms> still bounds individual network requests.

A wait timeout returns exit 9 with data.status=timed_out; SIGINT/SIGTERM cancels the local waiter with exit 10, leaving the server approval unchanged, while authentication, network, and protocol failures stop the wait with the existing error envelope.

Automatic continuation depends on the execution host keeping the process alive and delivering its completion; this is a local waiting process, not a new server-side durable job.

Use --brief or --signatures on Tool list/search to avoid printing full schemas. inspect renders a compact TypeScript-style signature and a copyable example; add --schema for the raw input schema. Near-miss Tool names receive a suggestion but are never silently rewritten.

Call output supports --output auto|text|json|raw. Image and embedded resource blocks are written only when --save-images <dir> or --save-resources <dir> is explicit; generated safe names never reuse an upstream resource path.

Diagnostics, generation, and replay

proxima doctor --exit-code
proxima doctor --quiet

# Generate a small typed surface; every real call still re-authorizes through Proxima
proxima mcp emit-ts github_work__list_issues \
  --mode client --out generated/github.ts

# Generate a single-purpose executable Node source backed by the shared runtime
proxima mcp generate-cli github_work__list_issues \
  --name proxima-github --out bin/proxima-github

# Record a redacted call fixture and inspect it later without network access
proxima mcp tools call github_work__list_issues repo=acme/demo \
  --record fixtures/github-list.ndjson
proxima mcp replay fixtures/github-list.ndjson \
  --tool github_work__list_issues --args-json '{"repo":"acme/demo"}'

# Inspect an existing client configuration without importing or executing it
proxima mcp config import --from cursor --file .cursor/mcp.json --dry-run

Generated TypeScript and CLIs contain Tool schemas, a digest, and a profile reference only. They do not contain API Keys, Connector credentials, or approval tokens. The exported @aido.ai/proxima/runtime re-fetches the Tool catalog, applies schema defaults, validates arguments, rejects destructive Tools, requires confirmWrite: true for mutation, accepts an explicit approvalId retry, and returns CallResult<T> helpers whose type matches the normalized MCP result contract.

Record fixtures contain redacted MCP JSON-RPC send/receive/lifecycle NDJSON. Authorization, Proxima Keys, approval identifiers, signed query values, password/token/secret fields are recursively redacted; directories use mode 0700 and files 0600. Replay replaces the network transport, matches the recorded method and redacted parameters, rewrites the active request ID, and rejects mismatches or unused requests. Configuration inspection currently accepts JSON server maps; TOML and JSONC inputs require conversion to JSON first.

Generated single-purpose CLIs are governed launchers that depend on @aido.ai/proxima; they reuse the full CLI command core for friendly arguments, confirmation, approval retry, output envelopes, exit codes, content handling, and recording. They are not bundled standalone binaries.

Agent-friendly JSON

Put the global --json flag before the command:

proxima --json skills search postgres
proxima --json mcp tools list

stdout contains exactly one envelope:

{
  "ok": true,
  "command": "skills.search",
  "status": "success",
  "data": { "items": [] },
  "error": null
}

Authorization values, prx_ strings and common signed query parameters are redacted from errors and output.

Exit codes

| Code | Meaning | | ---: | --- | | 0 | Success | | 2 | Usage or configuration error | | 3 | Authentication or scope rejected | | 4 | Network, timeout or response-size failure | | 5 | MCP/Registry protocol or server error | | 6 | Not found or unsupported target | | 7 | Bundle or security verification failed | | 8 | MCP tool returned an error | | 9 | Proxima owner approval required | | 10 | Local confirmation declined or unavailable |

Development checks

npm test
npm run typecheck
npm run build
npm pack --dry-run