nagent CLI

nagent is the command-line client for SimpleAgent deployments.

Install

uv tool install nagent-cli
nagent --help

If uv has stale package metadata immediately after a release, refresh the package cache:

uv tool install --force --refresh-package nagent-cli nagent-cli

To install a specific version:

uv tool install 'nagent-cli==0.4.5'

Log in

Use the API base URL and management key provided by your workspace administrator. For a human terminal, omit the key option and use the hidden prompt:

nagent login --api-base-url https://<api-hostname>

For non-interactive use, send the key as one bounded line through a non-terminal pipe so it never appears in argv or an environment variable. For example, read an existing key from macOS Keychain:

security find-generic-password -w -s nagent-staging-management \
  | nagent login --api-base-url https://<api-hostname> --api-key-stdin

--api-key-stdin is mutually exclusive with --api-key and with prompting. It rejects terminal, EOF/empty, multi-line, invalid UTF-8, and oversized input. Agent and JSON modes never prompt; they require --api-key-stdin (preferred) or the less-safe explicit --api-key argument.

This input changes only the local 0600 CLI credential file. It does not change a management API request/response or server schema, so Nagent Console, ui/manifest.yaml, and generated OpenAPI/UI types intentionally have no corresponding field or flow.

Common commands

nagent models list
nagent tools list
nagent secrets list
nagent deploy ./agent --deployment prod
nagent versions list <agent-name>
nagent run prod 'Hello'

nagent run submits with wait=false and polls the returned /runs/{run_id} resource by default. --stream is human-only: it follows /runs/{run_id}/events over SSE after submission, then confirms final status by polling. --wait instead uses one blocking request and is more susceptible to intermediary timeouts. The start request contains only message and wait; streaming is a separate run-resource transport.

nagent versions list <agent-name> reports each immutable version's public manifest summary, including all configured limits (max_runtime_seconds, max_tool_calls, max_concurrent_runs, max_total_tokens, and max_cost_usd). Human, --agent, and --json modes expose the same public-safe values; internal runtime and package metadata is never included.

With a stored management key, nagent run-log <run_id> fetches the public-safe workspace diagnostic from /api/runs/{run_id}/log. It has no raw mode and cannot return package refs, exact secret/version IDs, raw Pi events, worker/runtime internals, or private paths.

Agent bundles contain:

• AGENTS.md — agent instructions
• agent.yaml — public model/tool manifest

Validate a bundle locally before deploying:

nagent inspect-bundle ./agent

Machine-readable output

Use deterministic plain text for agents and scripts:

nagent deployments list --agent

Use JSON for structured automation:

nagent deployments list --json

Export deployed source

Fetch the current deployed bundle for inspection or local editing:

nagent deployments get-bundle prod --out ./prod-bundle

This writes AGENTS.md, agent.yaml, and deployment-bundle.json with logical secret binding names only. Existing files are not overwritten unless --force is supplied.

AGENT_SESSION=1 selects agent mode by default unless --json is supplied.

Upgrade

uv tool upgrade nagent-cli