CLI and branding
aidy is a generic command line for every aidy host. It has no host commands built in: it connects to <host>/mcp, lists the tools the signed-in user may use, and turns each into a command. The same binary also generates a host’s documents and keys. Node 22 or later is required.
npm install -g @aidy-dev/cliUse a host
Section titled “Use a host”aidy login https://console.example.com # asks for the token; or --token-stdin < token.txtaidy tools # every command the host offers youaidy vm stop gpu-train-01 --forced # a host commandaidy vm stop --help # its flagsaidy search "gpu box"aidy status # host, credential, server, tool countaidy logout- The built-ins are
login,logout,status,toolsandsearch. A host command whose first word is one of them wins;aidy:<name>always runs the built-in (aidy aidy:login, alsoaidy:skilland the other authoring commands). - Every command takes
--help(-h), built-ins and authoring commands included. - The tool list is cached per host and token for five minutes in
~/.cache/aidy.
Host and token
Section titled “Host and token”| Host | Token | |
|---|---|---|
| 1 | --host <url> |
AIDY_TOKEN |
| 2 | AIDY_HOST |
the token login saved for the host |
| 3 | the last host aidy login logged in to |
|
| 4 | a branded CLI’s preset host, if it has one |
Flags win over the environment, which wins over the saved login. In CI, set the variables and skip login:
AIDY_HOST=https://console.example.com AIDY_TOKEN=… aidy vm list # no login, nothing on diskloginsaves the token it reads (on the terminal, or--token-stdin) per host in~/.config/aidy/hosts.json(mode 0600), with the default host per program, soaidyand each branded CLI keep their own default.- A token from the environment is never written to disk:
logindoes not read it, and the tool cache is keyed by a hash. WhenAIDY_HOSTis set,AIDY_TOKENgoes to that host only;--hostto another host uses its saved login. - No command, error or help prints a token.
statussays which credential it used:"credential": "AIDY_TOKEN"or"login". - Positionals are the tool’s
args, in order. Every other input property is a flag:--page-size 20(_becomes-),--flag/--no-flagfor booleans, a repeated flag for arrays, JSON for objects, and--input-json file|-for the whole input (flags override it). - Output is JSON on stdout, pretty-printed on a terminal. Errors go to stderr.
Writes and confirmation
Section titled “Writes and confirmation”A write asks for confirmation through MCP elicitation. On a terminal, aidy shows the question; --yes (-y) accepts it. Without a terminal, the confirmation is declined unless --yes is given, so scripts must opt in explicitly. The host still checks the user’s own permissions on every call.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
| 0 | OK |
| 1 | Tool error |
| 2 | Usage error |
| 3 | Authentication |
| 4 | Network |
Shape commands with x-aidy.cli
Section titled “Shape commands with x-aidy.cli”By default an operation becomes one command: its name with _ replaced by -, without positionals (stop_vm → aidy stop-vm --vm-id vm-42). x-aidy.cli gives it words and positionals:
"x-aidy": { "name": "stop_vm", "cli": { "command": "vm stop", "args": ["vm_id"] }}Now the command is aidy vm stop vm-42. With resolve on vm_id, aidy vm stop gpu-train-01 works too.
The spelling reaches the CLI as _meta.aidy on each MCP tool:
{ "name": "stop_vm", "_meta": { "aidy": { "command": "vm stop", "args": ["vm_id"], "effect": "update" } } }toolMeta(op) in @aidy-dev/documents builds it from a catalog operation. A tool without _meta.aidy becomes one command named after the tool.
The CLI only sees operations whose surfaces include cli, which is the default for every effect. See Operations.
Authoring commands
Section titled “Authoring commands”These run against an OpenAPI file or URL (--openapi), without a host login.
aidy check --openapi openapi.json --routes routes.txtaidy skill --openapi openapi.json --product "Acme Cloud" --url https://console.example.com \ --guide guide.md --cli-command acme -o SKILL.mdaidy llms --openapi openapi.json --product "Acme Cloud" --url https://console.example.com \ --summary "Cloud servers on demand." -o llms.txtaidy reference --openapi openapi.json -o reference.mdaidy docs --openapi openapi.json --product "Acme Cloud" --url https://console.example.com \ --summary "Cloud servers on demand." -o docs/aidy keys generate --kid aidy-2026-11 -o aidy-2026-11.private.jwkcheckprints every catalog issue and exits 1 when there is any.--routeslists the UI’s requests asMETHOD /path, one per line; a route that no catalog operation serves fails unless it is marked# browser-only: <reason>. Run it in CI to keep the agent’s reach equal to the UI’s.skill,llms,referenceanddocswrite the same documents aidy serves at/skill.mdand/llms.txt, as files for your repository or docs site.keys generateprints the public JWK (for the host) and writes the private JWK (aidy’s signing key) to a new 0600 file. Both are portable (kty,crv,x,d,kid, withoutalg), so Node, Bun, Deno and workerd import them alike.aidy-server keys <kid>from@aidy-dev/serveralso makes a pair, but prints both halves as JSON on stdout. See Deploy.
Ship a branded CLI
Section titled “Ship a branded CLI”aidy brand writes a small npm package whose bin runs aidy under your product’s name:
aidy brand --name acme --host https://console.example.com -o acme-cli --npm-name @acme/clicd acme-cli && npm publish --access public--host <url>is optional: the preset host, used when no--host, environment variable oracme login <url>names one. A self-hosted product has no single host: leave it out, and users runacme login https://acme.example.comor set the host variable.--env-host VARand--env-token VARname the variables the CLI reads. They default to<NAME>_HOSTand<NAME>_TOKEN, the name uppercased with-→_(acme→ACME_HOST,ACME_TOKEN); the genericaidyfollows the same rule. A product with its own variables keeps them:
aidy brand --name acahti --env-host ACAHTI_ROOT_URL --env-token ACAHTI_TOKEN -o acahti-cliYour users then run:
npm install -g @acme/cliacme loginacme vm stop gpu-train-01acme vm stop gpu-train-01 runs like aidy --host https://console.example.com vm stop gpu-train-01, with acme in help and errors, its own variables and its own default host. --npm-name defaults to <name>-cli. The package depends on @aidy-dev/cli, so a new aidy release reaches it through a normal dependency update. Commands come from the host at run time, so new operations appear without republishing.
To embed the CLI in your own program, call the library:
import { run } from '@aidy-dev/cli';
process.exitCode = await run(process.argv.slice(2), { program: 'acme', host: 'https://console.example.com', // optional preset env: { host: 'ACME_HOST', token: 'ACME_TOKEN' }, // the defaults for acme});Every flag and command is listed in the CLI reference.