Skip to content

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.

Terminal window
npm install -g @aidy-dev/cli

For a walkthrough, see the CLI guide.

Usage: aidy [--host <url>] [--yes] <command> [args]

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

Terminal window
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.

Terminal window
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.

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.

Terminal window
aidy tools [--json]

Every command the host offers you, one per line with its summary and effect. --json prints [{command, tool, args, effect?, description}].

Terminal window
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.

Terminal window
aidy <command words> [positionals] [--flags]
aidy <command words> --help

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

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

Terminal window
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/vms
POST /api/vm/{vm_id}/stop
GET /api/session/ping # browser-only: keepalive for the UI

See validation failures.

Terminal window
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.

Terminal window
aidy llms --openapi <file|url> --product <name> --url <url> --summary <text> [-o llms.txt]

Writes llms.txt per llmstxt.org.

Terminal window
aidy reference --openapi <file|url> [-o reference.md]

Writes a Markdown reference of every operation.

Terminal window
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.

Terminal window
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.

Terminal window
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.

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