CLI
aidy is the command line of every aidy host, and the authoring tool for a host’s catalog. It needs Node 22 or later.
npm install -g @aidy-dev/cliFor a walkthrough, see the CLI guide.
Usage: aidy [--host <url>] [--yes] <command> [args]Global flags
Section titled “Global flags”Global flags come before the command.
| Flag | Meaning |
|---|---|
--host <url>, --host=<url> |
The host to use. An http or https URL; a trailing slash is dropped. |
--yes, -y |
Confirm writes without asking. |
--help, -h |
Print usage. aidy help does the same. After a command, its own help. |
Environment
Section titled “Environment”| Variable | Meaning |
|---|---|
AIDY_HOST |
The host, when no --host is given. |
AIDY_TOKEN |
The token. Sent to AIDY_HOST when that is set, else to whichever host is used; never written to disk or printed. |
A branded CLI reads its own names, <NAME>_HOST and <NAME>_TOKEN by default (see brand).
The host is --host, else AIDY_HOST, else the last host aidy login logged in to, else a branded CLI’s preset host. The token is AIDY_TOKEN, else the token login saved for that host. Without a host, aidy exits 3 with no host; pass --host <url>, set AIDY_HOST, or run aidy login <url>.
Host commands
Section titled “Host commands”Host commands connect to <host>/mcp (MCP streamable HTTP, bearer token) with the token above.
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), and the authoring commands are reachable the same way (aidy:skill). Every command takes --help (-h).
aidy login [host-url] [--token-stdin]Stores a token for the host and makes it the default of this program. Without --token-stdin, aidy asks for the token on the terminal without echoing it; without a terminal, --token-stdin is required. It never reads AIDY_TOKEN. login connects and lists the tools to check the token, then prints {"host", "tools"}. The host comes from the argument, else --host, else AIDY_HOST.
logout
Section titled “logout”aidy logout [host-url]Forgets the host’s token and its cached tool list. Without an argument it logs out of --host, else the default host.
status
Section titled “status”Prints the host, the credential used (login or the name of the token variable), the MCP server’s name and version, and how many tools it offers you. It never prints the token:
{ "host": "https://console.example.com", "credential": "AIDY_TOKEN", "server": { "name": "…", "version": "…" }, "tools": 42 }status replaces whoami.
aidy tools [--json]Every command the host offers you, one per line with its summary and effect. --json prints [{command, tool, args, effect?, description}].
search
Section titled “search”aidy search "gpu box"On an aidy host, this runs the host’s search tool: federated search over the product’s search operations and knowledge. The built-in, for a host without one (or as aidy:search), lists the commands whose words, name or description hold every word of the query.
Host tool commands
Section titled “Host tool commands”aidy <command words> [positionals] [--flags]aidy <command words> --helpCommands are not built in. aidy lists the host’s MCP tools and spells each as the words in its _meta.aidy:
{ "name": "stop_vm", "_meta": { "aidy": { "command": "vm stop", "args": ["vm_id"], "effect": "update" } } }A tool without _meta.aidy becomes one command, its name with _ replaced by -, without positionals. The longest matching command wins. The spelling comes from x-aidy.cli.
| Input | Spelling |
|---|---|
| Positionals | The tool’s args, in order. |
| Other properties | --page-size 20: _ becomes -. --name=value also works. |
| Booleans | --flag, --no-flag, or --flag=true/--flag=false. |
| Arrays | Repeat the flag: --tag a --tag b. |
| Objects | A JSON object: --labels '{"team":"ml"}'. |
| Numbers | Checked: integers must be whole. |
| Whole input | --input-json <file|->: a JSON object from a file or stdin. Flags override its keys. |
| End of flags | --: everything after it is positional. |
| Confirm | --yes, -y (unless the tool itself has a yes property). |
| Help | --help, -h: usage, description, every flag, and -y for writes. |
Missing required inputs fail with exit code 2 before anything is sent.
Writes. The host asks for confirmation through MCP elicitation. On a terminal aidy shows the question and waits for y; --yes accepts it; without a terminal it declines and says to pass --yes.
Output. The tool’s structured content, else its single text content parsed as JSON, is printed as JSON on stdout: pretty on a terminal, one line otherwise. A tool error is printed to stderr as error: … with exit code 1.
Authoring commands
Section titled “Authoring commands”--openapi takes a JSON file or an http(s) URL. -o/--out writes to a file; without it, output goes to stdout. Authoring commands reject unknown flags with exit code 2; --help prints a command’s usage.
aidy check --openapi <file|url> [--routes routes.txt]Prints every catalog issue as <where>: <message> and exits 1 when there is any; otherwise prints ok: N operations to stderr. --routes is a list of the UI’s METHOD /path requests, one per line. A route no catalog operation serves fails unless marked # browser-only: <reason>:
GET /api/vmsPOST /api/vm/{vm_id}/stopGET /api/session/ping # browser-only: keepalive for the UISee validation failures.
aidy skill --openapi <file|url> --product <name> --url <url> [--guide guide.md] [--cli-command acme] [-o SKILL.md]Writes the agent skill: frontmatter, the hand-written guide, how to connect (MCP at <url>/mcp, and the CLI when --cli-command is given), safety rules and the operation index.
aidy llms --openapi <file|url> --product <name> --url <url> --summary <text> [-o llms.txt]Writes llms.txt per llmstxt.org.
reference
Section titled “reference”aidy reference --openapi <file|url> [-o reference.md]Writes a Markdown reference of every operation.
aidy docs --openapi <file|url> --product <name> --url <url> --summary <text> [--guide f] [--cli-command c] -o <dir>Writes SKILL.md, llms.txt and reference.md into the directory and prints their paths as JSON.
keys generate
Section titled “keys generate”aidy keys generate --kid aidy-2026-11 [-o aidy-2026-11.private.jwk]Generates an Ed25519 key pair. Prints the public JWK (for the host’s configuration) on stdout and writes the private JWK (aidy’s signing key) to a new file with mode 0600, by default <kid>.private.jwk. It never overwrites a file and never prints the private key. Both are portable, {kty, crv, x, kid} and {kty, crv, x, d, kid} without alg, key_ops or ext, so Node, Bun, Deno and workerd import them alike. See Delegation.
aidy brand --name acme [--host https://console.example.com] [--env-host VAR] [--env-token VAR] -o acme-cli [--npm-name @acme/cli]Writes a small npm package (package.json, bin/acme.js, README.md) whose bin acme runs aidy as acme. --name must be a lowercase command name; --npm-name defaults to <name>-cli.
| Flag | Meaning |
|---|---|
--host <url> |
Optional preset host, used when no --host, environment variable or saved login names one. Leave it out for a self-hosted product. |
--env-host VAR, --env-token VAR |
The variables the CLI reads. Default <NAME>_HOST and <NAME>_TOKEN: the name uppercased, - → _ (acme → ACME_HOST, ACME_TOKEN). |
| Path | Content |
|---|---|
~/.config/aidy/hosts.json |
Tokens saved by login per host, and the default host per program. Mode 0600, directory 0700. Tokens are never printed; a token from the environment is never stored. |
~/.cache/aidy/tools/<hash>.json |
The tool list, cached per host and token (by hash) for five minutes. login and status always refresh it. |
XDG_CONFIG_HOME and XDG_CACHE_HOME move these directories.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 |
OK. |
1 |
Tool error: the tool answered an error, a JSON-RPC error, or check found issues. |
2 |
Usage: unknown command or flag, a missing or invalid value. |
3 |
Auth: no host, not logged in, or the host answered 401 or 403. |
4 |
Network: the host cannot be reached, or answered another HTTP error. |
Library
Section titled “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' },});run(argv, {program?, host?, env?, io?}) answers the exit code. program is the name shown in help and the key of its default host; host is the preset host; env names the host and token variables (default <PROGRAM>_HOST, <PROGRAM>_TOKEN).