Skip to content

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.

Terminal window
npm install -g @aidy-dev/cli
Terminal window
aidy login https://console.example.com # asks for the token; or --token-stdin < token.txt
aidy tools # every command the host offers you
aidy vm stop gpu-train-01 --forced # a host command
aidy vm stop --help # its flags
aidy search "gpu box"
aidy status # host, credential, server, tool count
aidy logout
  • The built-ins are login, logout, status, tools and search. A host command whose first word is one of them wins; aidy:<name> always runs the built-in (aidy aidy:login, also aidy:skill and 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 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:

Terminal window
AIDY_HOST=https://console.example.com AIDY_TOKEN=… aidy vm list # no login, nothing on disk
  • login saves 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, so aidy and each branded CLI keep their own default.
  • A token from the environment is never written to disk: login does not read it, and the tool cache is keyed by a hash. When AIDY_HOST is set, AIDY_TOKEN goes to that host only; --host to another host uses its saved login.
  • No command, error or help prints a token. status says 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-flag for 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.

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.

Code Meaning
0 OK
1 Tool error
2 Usage error
3 Authentication
4 Network

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.

These run against an OpenAPI file or URL (--openapi), without a host login.

Terminal window
aidy check --openapi openapi.json --routes routes.txt
aidy skill --openapi openapi.json --product "Acme Cloud" --url https://console.example.com \
--guide guide.md --cli-command acme -o SKILL.md
aidy llms --openapi openapi.json --product "Acme Cloud" --url https://console.example.com \
--summary "Cloud servers on demand." -o llms.txt
aidy reference --openapi openapi.json -o reference.md
aidy 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.jwk
  • check prints every catalog issue and exits 1 when there is any. --routes lists the UI’s requests as METHOD /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, reference and docs write the same documents aidy serves at /skill.md and /llms.txt, as files for your repository or docs site.
  • keys generate prints 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, without alg), so Node, Bun, Deno and workerd import them alike. aidy-server keys <kid> from @aidy-dev/server also makes a pair, but prints both halves as JSON on stdout. See Deploy.

aidy brand writes a small npm package whose bin runs aidy under your product’s name:

Terminal window
aidy brand --name acme --host https://console.example.com -o acme-cli --npm-name @acme/cli
cd acme-cli && npm publish --access public
  • --host <url> is optional: the preset host, used when no --host, environment variable or acme login <url> names one. A self-hosted product has no single host: leave it out, and users run acme login https://acme.example.com or set the host variable.
  • --env-host VAR and --env-token VAR name the variables the CLI reads. They default to <NAME>_HOST and <NAME>_TOKEN, the name uppercased with - → _ (acme → ACME_HOST, ACME_TOKEN); the generic aidy follows the same rule. A product with its own variables keeps them:
Terminal window
aidy brand --name acahti --env-host ACAHTI_ROOT_URL --env-token ACAHTI_TOKEN -o acahti-cli

Your users then run:

Terminal window
npm install -g @acme/cli
acme login
acme vm stop gpu-train-01

acme 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.