@startanaicompany/agentz

Client CLI for the agentz subagent registry — discover, install, and update Claude Code subagents inside any Node-based container.

Talks to a running agentz server over HTTPS. Authenticates with the per-agent SAAC_AGENT_API_KEY injected by tech.saac at provisioning — agentz validates it server-side via tech.saac's MCP orchestrator, no shared secrets. Zero runtime config files — everything is environment variables.

Install

npm install -g @startanaicompany/agentz

Or, for one-off use without a global install:

npx @startanaicompany/agentz list

Configuration

Set these in the consumer's environment:

| Variable | Required | Default | Purpose | |---|---|---|---| | AGENTZ_API_URL | no | https://agentz.startanaicompany.com | Base URL of the agentz server (override for self-hosted/dev) | | SAAC_AGENT_API_KEY | yes | — | Per-agent token issued by tech.saac. No fallback — must come from container provisioning. | | AGENTZ_INSTALL_DIR | no | $HOME/.claude/agents | Where installed .md files are written |

Usage

agentz list                       # list all available agents
agentz search "invoice"           # full-text search over name + description
agentz show code-reviewer         # show metadata + all versions for an agent
agentz install code-reviewer      # install latest version
agentz install [email protected]  # install a specific version
agentz install foo --force        # overwrite an existing hand-authored foo.md
agentz installed                  # list locally installed agents with versions + SHAs
agentz update                     # update all installed agents
agentz update code-reviewer       # update a single agent
agentz remove code-reviewer       # remove a locally installed agent

All list-style commands support --json for machine-readable output.

How install works

1. GET /api/v1/agents/{name}/download?version=<v> returns the canonical AGENT.md bytes.
2. The response includes an X-Agentz-SHA256 header; the CLI verifies the downloaded bytes against it before touching disk.
3. If $AGENTZ_INSTALL_DIR/{name}.md already exists but isn't tracked by agentz (no entry in .agentz-manifest.json), install fails unless --force is passed — in which case the pre-existing file is backed up to {name}.md.bak-<unix_ts> before being overwritten.
4. The index file $AGENTZ_INSTALL_DIR/.agentz-manifest.json is updated with {name, version, sha256, installed_at} for use by installed, update, and remove.

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Usage error (bad args) | | 2 | Auth error (missing/invalid SAAC_AGENT_API_KEY) | | 3 | Not found (agent or version) | | 4 | Network error | | 5 | Integrity error (SHA mismatch) | | 6 | Collision (untracked .md exists; pass --force to overwrite) |

Related

• agentz server + Python CLI: https://github.com/Ryan-SAAS/agentz
• Live registry: https://agentz.startanaicompany.com/docs

License

MIT