@startanaicompany/secretz

Agent-side CLI for the secretz per-company vault — read and write secrets (API keys, tokens, env values) from any agent or assistant container on the SAAC platform.

Talks to the secretz server over HTTPS using the SAAC_AGENT_API_KEY already injected into every agent/assistant container. Zero config files.

Install

npm install -g @startanaicompany/secretz

Or ad-hoc:

npx @startanaicompany/secretz list

Configuration

| Variable | Required | Default | Purpose | |---|---|---|---| | SAAC_AGENT_API_KEY | yes | — | The ag_… key injected into every agent/assistant container | | SECRETZ_TOKEN | no | — | Local-dev fallback for SAAC_AGENT_API_KEY | | SECRETZ_API_URL | no | https://secretz.startanaicompany.com | Server base URL |

Usage

secretz whoami                          # who am i? which orgs can i reach?
secretz list                            # list metadata for my org (or across all orgs for multi-org assistants)
secretz list --org <id> --json          # scoped + machine-readable

secretz get STRIPE_KEY                  # raw value to stdout (no newline)
export STRIPE_KEY=$(secretz get STRIPE_KEY)

echo "sk-live-…" | secretz set STRIPE_KEY
secretz set STRIPE_KEY --from-file key.txt --description "prod stripe"
secretz set STRIPE_KEY --from-env STAGING_STRIPE

secretz remove STRIPE_KEY

Values are intentionally read from stdin / file / env by default so they don't show up in shell history. You can pass them as a positional, but prefer one of the safer inputs.

secretz:// references

Agents and assistants can embed refs in HIVE messages and prompts so raw values never leak into the network:

Hey worker, charge with secretz://STRIPE_KEY for the pending invoices.

When you need the value, dereference it on-demand:

secretz get STRIPE_KEY | charge-tool

Or, if you have a block of text with multiple refs:

echo "$PROMPT" | secretz resolve > resolved.txt
# replaces every secretz://NAME in the text with its value

The audit log on the server records your agent as the reader, not HIVE — that's by design.

Org resolution

The server always wants an org_id in the path. The CLI fills it in for you:

• Agent (single-org): uses the sole org automatically; --org optional.
• Assistant with one org: same behavior.
• Assistant across multiple orgs: list falls back to a cross-org metadata listing; get / set / remove require --org <id> so you're always explicit about which company's vault you're touching.

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Usage error (bad args, validation failure) | | 2 | Auth error (missing/invalid key) | | 3 | Not found (secret) | | 4 | Network / upstream error | | 5 | Conflict | | 6 | Forbidden (org you don't belong to) |

Security

• Values are encrypted at rest with a per-org AES-256-GCM key that lives in tech.saac, never on disk in secretz or on your machine.
• The CLI never writes the value anywhere — it's streamed to stdout once and that's it. secretz get has no cache or history file.
• Every read/write/delete/list is audit-logged on the server against your agent identity.

Links

• Server source + issues: https://github.com/Ryan-SAAS/secretz
• Live vault: https://secretz.startanaicompany.com
• Sibling CLI: @startanaicompany/skillz

License

MIT