arizuko › reference › CLI

CLI

The subcommands of the arizuko binary, grouped by concern. Each entry shows the signature, the flags, the state that the command changes, and the source file. The dispatch map is in cmd/arizuko/main.go. The last section names the subcommands that this page does not describe.

The CLI uses the standard Go flag package and a small positional dispatcher. The first argument is the command. Every command except talk and probe takes -i/--instance NAME anywhere before --; without it the command uses the configured default instance. The short letters mean the same in every command: -i instance, -g group folder, -f force, -t token, -p product. -s is the scope of a token. -h/--help prints the usage of a command to stdout and exits 0. A few flags have no short form: --thread and --prompt of talk, and --seq of route add. <instance> is the suffix of the data directory: $ARIZUKO_DATA_DIR/arizuko_<name>, else ${PREFIX:-/srv}/data/arizuko_<name> (main.go).

Instance lifecycle

arizuko create [-i NAME] [-p|--product <product>]

Seed an instance data dir: write .env with a generated AUTH_SECRET and SECRETS_KEY, make services/, surrogate/ and store/, and set up the default group's folder. It writes files and no row — there is no store server yet. If --product is given, it reads ant/examples/<product>/arizuko.yml, writes the choice to .env as ARIZUKO_DEFAULT_PRODUCT, prints the env checklist. It copies no workspace file. At its first boot routd writes the main group row with that product and one installed_packages row for main; the next arizuko package sync installs the files.

State touched: creates ${PREFIX:-/srv}/data/arizuko_<name>/, writes .env (mode 0600), makes the services/, surrogate/ and store/ dirs, calls container.SetupGroup for the main folder skeleton. No row: routd seeds the ACL floor and the main group row at its first boot. Idempotent on .env (only written when missing).

arizuko create -i solo
arizuko create -i launch --product strategy

Source: cmd/arizuko/main.go

arizuko generate [-i NAME]

Generate docker-compose.yml in the instance directory from compose.Generate, with a tempfile and a rename; mode 0644. The command also links unchanged catalog fragments again, writes the proxyd_routes rows to the store of routd.

State touched: <data-dir>/docker-compose.yml, services/ links, proxyd_routes rows and group skill directories.

arizuko generate -i demo

Source: cmd/arizuko/main.go

arizuko run [-i NAME]

Generate the compose file (same path as generate), then docker compose -f <compose> up --remove-orphans. Foreground process; SIGINT propagates to the compose stack.

State touched: the same as generate, then docker state.

arizuko run -i demo

Source: cmd/arizuko/main.go

arizuko status [-i NAME]

docker compose ps against the instance compose file, then GET http://localhost:<APIPort>/v1/channels on the router with a 10s timeout. Prints registered channel name → URL pairs, or a "router API unreachable" / "no channels registered" line.

State touched: read-only. Requires docker-compose.yml to exist (will die with a "run 'arizuko generate' first" hint).

arizuko status -i demo

Source: cmd/arizuko/main.go

arizuko pair [-i NAME] <service> [-- container args...]

Run a one-shot pairing/admin shell against a compose service: docker compose -f <compose> run --rm <service> [container args...]. Container arguments follow --; a flag before -- that pair does not know is refused. Used for interactive setup of channel adapters (e.g. whapd QR pairing).

State touched: whatever the chosen service does. --rm removes the container on exit.

arizuko pair -i demo whapd

Source: cmd/arizuko/main.go

Config manifests

These commands read and compare cold-tier resources as YAML. They never select packages: the package commands do that, and the packages reference explains the package definition.

arizuko get [-i NAME] <resource>

Write the rows of one resource from the live store as YAML. Secret values do not leave the store. The output is a rows file that apply takes.

arizuko get -i demo groups > rows.yml

arizuko plan [-i NAME] <rows.yml>

Show what apply of the same file would add or change, without writing to the store.

arizuko plan -i demo rows.yml

arizuko apply [-i NAME] <rows.yml>

Write the rows in the file and nothing else. The file has the format of routd.yaml and onbod.yaml in a dump, so you can unpack a dump, edit one of them and apply it. A row in the file replaces the whole stored row with the same key; start from the output of get. A row that the file does not name stays, and a resource that the file does not mention stays. The command never deletes a row. It does not use the checksum in the file. The flags --force and --stopped are for a dump only.

State touched: the rows named in the file.

arizuko apply -i demo rows.yml

Full-instance backup

A rows file carries what an instance is set up to do. A dump carries the instance: the same config, plus the encrypted secret values, the whole message history, the people still waiting to be let in, and every group's files — one tar you can move to another machine. authd’s and runed’s stores stay out: signing keys, login sessions and run records belong to the machine.

One thing deliberately stays behind: SECRETS_KEY. The encrypted secrets travel, the key that opens them does not — you carry that yourself, out of band. Restoring onto a machine whose key cannot decrypt them fails loudly instead of importing rubbish.

arizuko dump [-i NAME] [out.tar] [--quiesced]

Write the dump. Taken from a running instance it is a smear, not a snapshot: each part is read consistently, but a message can land between two reads, so the whole is a few seconds wide rather than one instant. That is usually fine, and the dump records which it is so a restore is never guessing. Stop the instance first and pass --quiesced when you need a true point-in-time image — the flag only stamps the label; it does not stop anything for you.

State touched: read-only.

arizuko dump -i demo demo-backup.tar
arizuko dump -i demo demo-backup.tar --quiesced

Source: cmd/arizuko/archive.go

arizuko apply [-i NAME] <dump.tar> [-f|--force] [--stopped]

Restore a dump. Config goes in first, so every group exists before its files arrive; then message history is appended (re-running the same dump changes nothing already there); then each group's files are unpacked.

Unpacking a group's files while an agent is writing them would corrupt both, so the restore takes that folder's run slot first — the same slot an agent turn takes, so the two can never overlap. This means the instance must be up and runed reachable, or you pass --stopped to say it is down. An unreachable runed is a hard stop, never a warning: proceeding is the exact accident the slot exists to prevent.

Three parts hold credentials — chat links, invites, and pending setup links. They stay out by default, and even with --force go in only when the target has none of their own. Otherwise a restore would quietly re-activate a link someone had revoked, which is still sitting in a chat somewhere. A group whose files already exist is skipped for the same reason unless you pass --force; whatever was skipped is listed in the report.

State touched: writes config, message history, secret values, onboarding admissions, and groups/<folder>/ trees.

arizuko apply -i demo demo-backup.tar --stopped
arizuko apply -i demo demo-backup.tar --force

Source: cmd/arizuko/archive.go

Packages

Three subcommands manage packages. Each selection is a row in the installed_packages resource. The arizuko.yml file in a package source defines that package and selects nothing. The package reference defines sources, standard assets, order, host builds and resource ownership.

arizuko package [-i NAME] add [-g|--group <folder>] [-f|--force] <source>

Install one package and record its selection. The source is catalog:<name>, a local directory or a Git source; a relative path resolves under HOST_APP_DIR. Without -g the selection covers the whole instance. With -g it covers that group only, and the group must exist. The command creates the resource rows and services that the package declares.

State touched: one installed_packages row, the package directory under <data-dir>/packages/, service files, package-owned rows, the group/ files of the group and docker-compose.yml.

arizuko package add -i demo catalog:teled
arizuko package add -i demo -g support ant/examples/support

Source: cmd/arizuko/sync.go

arizuko package [-i NAME] rm [-g|--group <folder>] <name>

Withdraw one selection with the rows and services that the package owns. Name the package by its name, not by its source. The core package cannot be withdrawn.

State touched: the installed_packages row, package-owned rows, service files and docker-compose.yml.

arizuko package rm -i demo teled

Source: cmd/arizuko/sync.go

arizuko package [-i NAME] sync

Install every selected package again from its source. The order is core first, then the order of add. A later package overrides an earlier one on the same skill, hook, bin/ or group/ path, and the command prints one line for each override. It rewrites each group/ file from the winning package. Restart services through the deployment procedure.

State touched: the same as package add, for every selection.

arizuko package sync -i demo
demo: kronael-tools overrides core on skills/diary

Source: cmd/arizuko/sync.go

Operator chat & messaging

arizuko chat [-i NAME] [-g|--group <folder>]

Launch claude (Claude Code CLI) wired via socat to <data-dir>/ipc/<folder>/gated.sock. The folder defaults to main. Writes a temporary mcpServers config and execs claude --mcp-config <tmp>. Local-operator only — socket-fs access is the auth.

State touched: none on disk beyond a deleted-on-exit tempfile. Anything the agent does via MCP tools mutates the store as usual.

Prereqs: instance running (socket exists), claude and socat on $PATH.

arizuko chat -i demo
arizuko chat -i team -g team/discord

Source: cmd/arizuko/main.go

arizuko send [-i NAME] <folder> [<message>] [-w|--wait | -S|--stream] [--stdin] [--from <sender>] [-t|--token <raw>] [-T|--topic <t>]

Put a message into the chat of a group as web:<folder>, and optionally wait until the turn of the agent ends. By default, the command writes the message directly into the store. With --token or $ARIZUKO_CHAT_TOKEN, it posts to the /chat/<token>/ endpoint at WEB_HOST instead; the scheme is http for localhost and 127.0.0.1, otherwise https. The store keeps no raw tokens, so the CLI cannot look one up. See the tokens reference for the token model.

State touched: one inbound message row, or one POST to the chat endpoint with --token.

arizuko send -i demo main "hello from cli"
arizuko send -i demo main "what's the status?" --stream
echo "long body" | arizuko send -i demo main --stdin --wait

Source: cmd/arizuko/send.go

arizuko token [-i NAME] <issue|list|revoke> ...

Manage the route tokens that back /chat/<token>/ visitor chat and /hook/<token> webhook ingest. Each token is one row in route_tokens mapping an opaque URL token to a JID and owner folder. issue mints a token for a web: or hook: JID and prints both the JID and the raw token (the token is shown once). list tabulates a folder's tokens. revoke deletes one by JID and reads the owner folder from the row. Pass <owner_folder> to name the owner explicitly. issue bearer <folder> -s|--scope s1,s2 [--ttl 1h] [--sub SUB] mints a folder-scoped ES256 access token with the active key of authd. Both issue chat and issue webhook take --context TEXT, which the agent gets as a <link-context> block.

State touched: issue inserts a route_tokens row; revoke deletes one; list is read-only. issue and revoke write an audit row.

arizuko token -i demo issue chat support
arizuko token -i demo issue webhook eng github
arizuko token -i demo list support
arizuko token -i demo revoke web:support

Source: cmd/arizuko/token.go

Groups & grants

All group verbs share the same store and dispatch under cmd/arizuko/main.go.

arizuko group [-i NAME] list

Print the folder of every group, one on each line.

State touched: read-only.

arizuko group -i demo list

Source: cmd/arizuko/main.go

arizuko group [-i NAME] add <jid> <folder> [-p|--product <name>]

Create a group bound to a channel JID. Folder is validated via groupfolder.IsValidFolder. Calls container.SetupGroup for the folder skeleton seeds default tasks, inserts the group row, then adds a route room=<JidRoom(jid)> -> <folder>. For Discord guild channels (jid prefix discord: but not discord:dm/) the command writes two routes: room=<room> verb=mention at seq -1 to the folder, and room=<room> at seq 0 to <folder>#observe. So only mentions start a turn.

State touched: filesystem (group skeleton), groups, routes, default-task seed, and with -p one installed_packages row.

arizuko group -i demo add whatsapp:120363042@g.us standup
arizuko group -i demo add discord:123456789/987654321 eng -p pm

Source: cmd/arizuko/main.go

arizuko group [-i NAME] rename <source> <destination>

Rename a folder subtree across the instance's stores and files. Use --map old=new for nested exceptions. Stop all writers and guests before execution. Produce a complete private inventory of owner tables and partition counts; the command checks the inventory against the store and owner credentials. Collisions stop preflight. Coordinate operands in ACL Params and Predicate require exact values; wildcard operands stop preflight. Ambiguous suffixed token JIDs also stop preflight. Platform chat IDs and historical text stay intact.

arizuko group -i team rename main team --map main/main=team/discord \
  --inventory /private/team-inventory.json --endpoint https://127.0.0.1:18444 --dry-run

Execution requires --stopped --yes --journal /private/team-rename. The private journal must sit outside the instance directory. Keep writers stopped through verification. To recover an interruption, repeat the original command with --resume or --rollback and the same inventory, mapping and journal. Preserve the journal and an independent store backup.

Source: cmd/arizuko/group_rename.go

arizuko group [-i NAME] rm [-f|--force] <folder>

Delete the group and every group under it with store.DeleteGroup, and sweep the rows of those folders: acl, routes, secrets, tasks and the other folder rows. A folder without a group row still has its orphan rows swept. The command first stops the live run of each removed folder at runed, using RUNED_URL and RUNED_TOKEN from the instance .env. When runed is unreachable, it removes nothing and exits non-zero. After every stop succeeds, it deletes the groups/, web/pub/ and web/priv/ directories of those folders and prints each deleted path. -f removes rows and directories without contacting runed: use it only when no run is live.

State touched: groups, the folder rows of the subtree and the three directories of each folder.

arizuko group -i demo rm standup

Source: cmd/arizuko/main.go

arizuko group [-i NAME] grant <sub> <pattern> [action] [--effect allow|deny] [--params <matcher>]

Authorize sub on a scope. The pattern ** with the default action writes acl_membership(sub, role:operator), because the operator permissions live on the role. Any other row writes acl(principal=sub, action, scope=pattern, effect, params). The action defaults to admin and the effect to allow. Valid actions: *, admin, interact, egress, web:publish, gh:write, mcp:*, mcp:<tool>, shell:env:<KEY>, ext:<provider>:<area>:<verb>, hold:mcp:<tool> and <resource>.<verb>. Idempotent. See grants reference for syntax.

State touched: acl_membership (for **) or acl table.

arizuko group -i demo grant google:alice@example.com 'solo/**'
arizuko group -i demo grant telegram:42 'corp/eng/sre'
arizuko group -i demo grant google:operator@example.com '**'   # operator role

Source: cmd/arizuko/main.go

arizuko group [-i NAME] ungrant <sub> <pattern>

Reverse of grant, with the same arguments. ** with the default action removes the operator membership edge. Any other row deletes the matching acl row.

State touched: acl_membership (for **) or acl table.

arizuko group -i demo ungrant google:alice@example.com 'solo/**'

Source: cmd/arizuko/main.go

arizuko group [-i NAME] grants [<sub>]

List grants. With no sub, it lists all grants. With a sub, it lists the grants of that subject. Columns: PRINCIPAL | ACTION | SCOPE | EFFECT | PARAMS | GRANTED_AT, then a MEMBER OF block for role memberships.

State touched: read-only.

arizuko group -i demo grants
arizuko group -i demo grants google:alice@example.com

Source: cmd/arizuko/main.go

Invites

Onboarding tokens consumed by onbod's invite landing. Dispatcher at main.go.

arizuko invite [-i NAME] create <target_glob> [-n|--max-uses N] [-e|--expires DURATION]

Mint an invite token whose redemption grants the user the given target_glob pattern. Prints token, target, max-uses, optional expiry.

State touched: invites table; issued_by_sub is set to the literal "cli".

arizuko invite -i demo create 'solo/**' --max-uses 1 --expires 72h
arizuko invite -i demo create 'corp/eng/**' --max-uses 5

Source: cmd/arizuko/main.go

arizuko invite [-i NAME] list [-b|--issued-by SUB]

List invites. Columns: REF | TARGET_GLOB | ISSUED_BY | ISSUED_AT | EXPIRES_AT | USED (where USED is used_count/max_uses).

State touched: read-only.

arizuko invite -i demo list
arizuko invite -i demo list --issued-by cli

Source: cmd/arizuko/main.go

arizuko invite [-i NAME] revoke <ref>

Revoke an invite by its reference from invite list. Later redemptions fail.

State touched: invites row marked revoked.

arizuko invite -i demo revoke <ref>

Source: cmd/arizuko/main.go

Gates (admission limits)

Daily admission limits that onbod applies to new users at onboarding. A spec names who the gate counts: * for everyone, github, google:domain=<d> or email:domain=<d>. Dispatcher at main.go.

arizuko gate [-i NAME] list

List gates as GATE | LIMIT/DAY | ENABLED. Prints no gates if empty.

State touched: read-only.

arizuko gate -i demo list

Source: cmd/arizuko/main.go

arizuko gate [-i NAME] add <spec> <N>/day

Upsert a gate at the given daily limit. Limit string accepts an optional /day suffix (stripped); must parse as a positive integer.

State touched: gates table.

arizuko gate -i demo add '*' 200/day
arizuko gate -i demo add 'google:domain=example.com' 1000

Source: cmd/arizuko/main.go

arizuko gate [-i NAME] rm <spec>

Delete a gate row by spec.

State touched: gates table.

arizuko gate -i demo rm '*'

Source: cmd/arizuko/main.go

arizuko gate [-i NAME] enable <spec>

Flip enabled to true on the row.

State touched: gates table.

arizuko gate -i demo enable '*'

Source: cmd/arizuko/main.go

arizuko gate [-i NAME] disable <spec>

Flip enabled to false on the row. The row stays so the spec/limit survives re-enable.

State touched: gates table.

arizuko gate -i demo disable '*'

Source: cmd/arizuko/main.go

Budget (cost caps)

Per-folder and per-user daily spend caps in cents, stored on groups.cost_cap_cents_per_day and user_profiles.cost_cap_cents_per_day. The cap is arizuko’s policy; the model gateway enforces it. routd’s pre-spawn gate pushes each cap to the gateway as a one-day budget and refuses the turn when the gateway’s meter is at it. budget show prints the cap, not the spend — the spend belongs to the gateway, and reading it needs a master key this CLI does not hold; see /dash/usage/. Without a gateway nothing enforces a cap, which routd logs at ERROR. Dispatcher at budget.go.

arizuko budget [-i NAME] set <folder|user> <name|sub> -d|--daily N

Set a daily cap (in cents) on a folder or user. --daily 0 removes the cap (uncapped). Negative values are rejected.

State touched: groups.cost_cap_cents_per_day (folder scope) or user_profiles.cost_cap_cents_per_day (user scope).

arizuko budget -i demo set folder corp/eng --daily 5000
arizuko budget -i demo set user google:alice@example.com --daily 1000
arizuko budget -i demo set folder solo/inbox --daily 0   # uncapped

Source: cmd/arizuko/budget.go

arizuko budget [-i NAME] show <folder|user> <name|sub>

Print the scope, the target and the cap. The spend line says that the model gateway meters it; the CLI does not read the spend.

State touched: read-only.

arizuko budget -i demo show folder corp/eng
arizuko budget -i demo show user google:alice@example.com

Source: cmd/arizuko/budget.go

Network allowlist

Per-folder egress rules. Each spawn’s own egress proxy is started with the resolved list baked in. Walks the folder ancestry on resolve. Dispatcher at network.go.

arizuko network [-i NAME] allow <folder> <target>

Add an allow rule binding a folder to a hostname (or other target form supported by store.AddNetworkRule). created_by is set to the literal "cli".

State touched: network_rules table.

arizuko network -i demo allow main api.github.com
arizuko network -i demo allow corp/eng api.openai.com

Source: cmd/arizuko/network.go

arizuko network [-i NAME] deny <folder> <target>

Remove an allow rule. allow and deny are a pair of verbs; deny deletes the row with store.RemoveNetworkRule.

State touched: network_rules table.

arizuko network -i demo deny main api.github.com

Source: cmd/arizuko/network.go

arizuko network [-i NAME] list [<folder>]

List rules. Without <folder>, lists all. With a folder, lists that folder's own rows (not inherited ones — use resolve for that). Columns: FOLDER | TARGET | CREATED_AT | CREATED_BY (root rows render as (root)).

State touched: read-only.

arizuko network -i demo list
arizuko network -i demo list corp/eng

Source: cmd/arizuko/network.go

arizuko network [-i NAME] resolve <folder>

Print the fully resolved allowlist for a folder — walks ancestry, dedupes, includes the root seeds from baseAllowlist in store/seed.go. One target per line. Useful for verifying what a folder’s proxy will accept.

State touched: read-only.

arizuko network -i demo resolve corp/eng/sre

Source: cmd/arizuko/network.go

Routes

The route table maps inbound messages to group folders. Each row is a seq (priority, lower wins), a match expression over message attributes, and a target folder. arizuko group add writes a route for you; use route to add the catch-all and cross-source rules by hand. Routes share their store with acl: both are routd's, on the instance's store server. Writes go through the audited AddRoute and DeleteRoute. Dispatcher at route.go.

arizuko route [-i NAME] list

List every route ordered by seq then id. Columns: ID | SEQ | MATCH | TARGET. An empty match renders as * (catch-all). Prints no routes if empty.

State touched: read-only.

arizuko route -i demo list

Source: cmd/arizuko/route.go

arizuko route [-i NAME] add <match> <target> [--seq N]

Add a route binding a match expression to a target folder. match is a space-separated set of key=value predicates (e.g. platform=telegram, verb=mention, chat_jid=hook:*/sentry/*); * or an empty string is the catch-all and is stored as an empty match. Prints added route <id>.

State touched: routes table and an audit row.

arizuko route -i demo add 'platform=telegram' supermarket
arizuko route -i demo add '*' corp/intake --seq 10
arizuko route -i demo add 'chat_jid=hook:*/sentry/*' corp/eng/sre --seq -10

Source: cmd/arizuko/route.go

arizuko route [-i NAME] rm <id>

Delete a route by id (from route list). Errors with no route <id> if it does not exist.

State touched: one routes row deleted and an audit row.

arizuko route -i demo rm 7

Source: cmd/arizuko/route.go

Secrets (folder & user)

Folder-scoped and user-scoped secrets backing the secret-broker model (see secrets). Keys must match ^[A-Z][A-Z0-9_]*$ (validated by store.ValidSecretKey in store/secrets.go).

arizuko secret [-i NAME] set <folder> KEY -v|--value V

Store a folder-scoped capability secret. --value is required; empty values rejected. Key is validated against the uppercase ENV-style pattern. The five model keys (ANTHROPIC_API_KEY, ANTHROPIC_OAUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, OPENAI_API_KEY, CODEX_API_KEY) are rejected at folder scope — they belong to the host .env or to a user at /dash/me/env.

State touched: secrets table, scope_kind = folder.

arizuko secret -i demo set corp/eng GITHUB_TOKEN --value ghp_xxxxxxxxxxxx
arizuko secret -i demo set main CF_API_TOKEN --value cf_xxxxxxxx

Source: cmd/arizuko/secret.go

arizuko secret [-i NAME] list <folder>

List keys (not values) for a folder. Columns: KEY | CREATED_AT. Prints no secrets if empty.

State touched: read-only.

arizuko secret -i demo list corp/eng

Source: cmd/arizuko/secret.go

arizuko secret [-i NAME] delete <folder> KEY

Delete one folder-scoped key.

State touched: secrets table row delete.

arizuko secret -i demo delete corp/eng GITHUB_TOKEN

Source: cmd/arizuko/secret.go

arizuko user-secret [-i NAME] set <user_sub> KEY -v|--value V

Operator fallback for setting a user-scoped secret on behalf of a user who has not logged in via /dash/me/secrets yet. Same key validation as secret set.

State touched: secrets table, scope_kind = user.

arizuko user-secret -i demo set google:alice@example.com GITHUB_TOKEN --value ghp_xxx

Source: cmd/arizuko/secret.go

arizuko user-secret [-i NAME] list <user_sub>

List keys for one user sub. Columns: KEY | CREATED_AT.

State touched: read-only.

arizuko user-secret -i demo list google:alice@example.com

Source: cmd/arizuko/secret.go

arizuko user-secret [-i NAME] delete <user_sub> KEY

Delete one user-scoped key.

State touched: secrets table row delete.

arizuko user-secret -i demo delete google:alice@example.com GITHUB_TOKEN

Source: cmd/arizuko/secret.go

Other subcommands

These subcommands exist in the binary. Their usage line is the reference; run the subcommand without arguments to print it.

See also

• reference index
• env vars — what the daemons themselves read
• MCP tools — the in-container surface the agent calls (often pairs with these CLI verbs)
• grants syntax — pattern language used by group grant and invite create
• cmd/arizuko/ — source of truth