CLI

The athenode CLI is what actually reads and writes your specification tree — it's what both you and your AI coding agent use to create specifications, answer their questions, move them through statuses, and record what got implemented. Everything the commands on the Commands reference page do, they do by calling this CLI underneath.

Every command that returns data prints raw JSON to stdout — nothing pretty-printed or truncated — so its output is safe to pipe into a script or parse programmatically. This is what makes the CLI usable both by an AI agent and by your own tooling.

Installation

Like the rest of Athenode's tooling, the CLI is run through npx, with no separate install step:

npx @athenode/cli <command>

init

init sets up a project to work with Athenode: it stores your project token, lets you pick which AI coding environments you use, and installs the matching agent setup's commands into each one. Run it once from your project's root directory to get started — see Getting started for the full first-time walkthrough.

The token and project id it stores live in .athenode/config.json, in your project's root directory. That file holds a secret (your project token), so add it to .gitignore — don't commit it to your repository.

Running init again

You can safely run init again on a project that's already set up — for example, to add another AI coding environment, switch to a different agent setup, or get a new project token. Running it again walks through the same steps as the first time, with a few differences:

1. Token. If a token is already stored, init asks whether to replace it (defaulting to "no") — answering no keeps using the stored token as-is; answering yes lets you paste in a new one.
2. Environment and agent setup selection happen again. init doesn't remember your previous choices — you pick your target environments and an agent setup fresh each time.
3. Files from the previous install are cleaned up first. Before writing anything new, init removes every file it installed the last time around, so switching environments or setups doesn't leave old, stale files behind.
4. Conflicting files are handled per file. For each file init wants to (re)write: if what's already on disk matches exactly, it's left alone. If a different file is already there, init asks whether to overwrite it, skip it, or show a diff first.
5. A summary line closes it out, reporting how many files were installed, how many were skipped due to conflicts, and how many were already up to date.

specs

The specs group is how you read and write the specification tree itself directly — the same operations your AI agent's commands (mind-mapping, decomposing, applying) perform internally.

Specification CRUD

Command	What it does	Flags
specs list	Lists specifications.	--status <status>, --parent <id>, --top-level
specs search <query>	Full-text search across specifications.	—
specs tree [id]	Fetches a subtree rooted at id, an ancestor lineage with --branch, or ranked full-text matches nested with their ancestors with --query.	--status <status>, --include-content, --branch, --query <text>
specs get <id>	Fetches a single specification.	—
specs create	Creates a new specification.	--title <title> (required), --parent <id>, --summary <text>, --content <text> (or piped via stdin), --status <status>
specs update <id>	Updates an existing specification's fields.	--title <title>, --summary <text> / --clear-summary, --content <text> (or piped via stdin) / --clear-content, --parent <id> / --clear-parent
specs set-status <id> <status>	Sets a specification's status.	—
specs set-plan <id>	Records an implementation plan on a specification.	--plan <text> / --clear-plan
specs get-plan <id>	Fetches a specification's recorded implementation plan.	—

Examples:

specs create --title "Getting Started" --status draft
specs get 92bb5776-6a15-4bc8-b2b5-b3a59fb2ac9a
specs update 92bb5776-6a15-4bc8-b2b5-b3a59fb2ac9a --title "Getting Started"
specs set-status 92bb5776-6a15-4bc8-b2b5-b3a59fb2ac9a prepared
specs tree e8d44d7c-9492-48a8-84f5-df7773c8fadb --status prepared
specs search "getting started"
specs list --top-level
specs set-plan 92bb5776-6a15-4bc8-b2b5-b3a59fb2ac9a --plan "..."
specs get-plan 92bb5776-6a15-4bc8-b2b5-b3a59fb2ac9a

Q&A

Used by the mind-mapping and decomposition commands to record each round of clarifying questions and their answers directly on a specification.

Command	What it does	Flags
specs qa list <specificationId>	Lists every recorded question/answer pair for a specification.	—
specs qa add <specificationId>	Adds a new question.	--question <text> (required)
specs qa answer <specificationId> <questionId>	Records the answer to a previously-added question.	--answer <text> (required)

Example:

specs qa add 92bb5776-6a15-4bc8-b2b5-b3a59fb2ac9a --question "What audience is this for?"
specs qa answer 92bb5776-6a15-4bc8-b2b5-b3a59fb2ac9a <questionId> --answer "Prospective customers"
specs qa list 92bb5776-6a15-4bc8-b2b5-b3a59fb2ac9a

Results

Used to record which files were touched while implementing a leaf specification.

Command	What it does	Flags
specs results list <specificationId>	Lists every recorded execution result for a specification.	—
specs results create <specificationId>	Records a touched file and a summary of what changed.	--file-path <path> (required), --summary <text> (required)

Example:

specs results create 92bb5776-6a15-4bc8-b2b5-b3a59fb2ac9a --file-path "landing/lib/docs/manifest.ts" --summary "Added the getting-started page node"
specs results list 92bb5776-6a15-4bc8-b2b5-b3a59fb2ac9a

What's next

• Getting started — set up Athenode and run your first command
• Commands reference — the higher-level commands your AI agent runs on top of this CLI