Metadata-Version: 2.4
Name: nagent-cli
Version: 0.4.5
Summary: Command-line client for SimpleAgent deployments
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# `nagent` CLI

`nagent` is the command-line client for SimpleAgent deployments.

## Install

```bash
uv tool install nagent-cli
nagent --help
```

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

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

To install a specific version:

```bash
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:

```bash
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:

```bash
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

```bash
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:

```bash
nagent inspect-bundle ./agent
```

## Machine-readable output

Use deterministic plain text for agents and scripts:

```bash
nagent deployments list --agent
```

Use JSON for structured automation:

```bash
nagent deployments list --json
```

## Export deployed source

Fetch the current deployed bundle for inspection or local editing:

```bash
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

```bash
uv tool upgrade nagent-cli
```
