Use the CLI with AI agents

For the docs an agent reads and the Akedly integration skill, see AI agents and LLMs.

Discover the commands for your task

akedly commands --fields name,help --output json
akedly describe "pipelines update" --output json

Start with the command names, then describe only the commands your task needs. Both commands work offline without a login. describe returns a status: "success" envelope whose data contains the command's business purpose, prerequisites, input and file schemas, wire mappings, response schema, worked examples, consent and recovery rules.

Quote the full command name, such as "pipelines update". Boolean flags are switches with no value; numbers and comma-separated lists are each one argument. File contracts distinguish the local reader's checks from fields validated by the server. Examples are synthetic: use your own authorized resources and keep secrets private.

Use the command reference to browse the same contracts by subject. The full handbook is optional when you need portable instructions for many commands:

akedly agent-guide
akedly agent-guide --write akedly-guide.md

akedly agent-guide prints portable instructions for an agent as Markdown (in JSON mode, as data.guide). --write <path> saves them to a new file. If the file already exists, the command exits 64 and suggests writing to a new file and referencing it from your AGENTS.md, or appending with akedly agent-guide --output human >> AGENTS.md. With --dry-run it writes nothing.

The guide and command reference are generated from the same command metadata.

Rules an agent should follow

• Set AKEDLY_OUTPUT=json. stdout is then one JSON document; warnings and progress go to stderr (progress events).
• Decide on the exit status, the error code and the hint, never on the message (exit codes).
• On exit 69, wait until details.retryAfter or for details.cooldownSeconds, then run the command again (retries).
• Pass --yes only when the person asked for that action. Commands that delete, spend money or send a real message require it, and so do some setup changes, such as role changes, callback URLs and quickstart.
• Use --dry-run to preview: it sends no messages and writes no guide or secret file. Commands that plan from current settings can still make read requests.
• After an unclear failure, check the state before repeating a command that changes or sends anything (commands that send or change things).
• Never print secrets, API keys, CLI Login credentials or live OTP fields into the chat. Use --secret-file or --save where a command offers them.
• Prefer dev-mode Test Pairs. Real sends can be billed.
• When the agent only needs to read, give it a Read-only login and no API key. Read-only limits that login only; the Sending Commands run on an API key and are not stopped by it (below).

The full list, as the CLI states it, is in Agent rules.

Choose an access level for the agent

You pick the access level when you approve the login.

JSON output

With no output setting at all, the CLI writes JSON whenever stdout is not a terminal. akedly commands --json returns every command as a bare array, so an agent can discover flags and permissions without reading docs. To keep only some fields, see Fields and JSON paths.

Pagination and big lists

Pagination varies by command. Where a command offers --all, it reads every page. Check the command's supported flags; the shared rules and limits are in Pagination.

Credentials for automation

Keep credentials and signing secrets out of prompts, logs and command arguments. The environment variables, including API and dashboard URL overrides, are listed in Headless machines and CI.