CLI Reference

Author

fariazinhu

Usage

aether [flags]

Aether opens an interactive session. No subcommands needed — everything happens through slash commands once it's running.

Flags

Interactive Commands

Once inside the session, use slash commands (case-insensitive: /CONFIG, /Genesis, etc. all work):

Every command also accepts help, --help, or -h for detailed usage — e.g. /config help.

/config

Configure the AI provider used by /genesis. Config is stored globally in ~/.aether/config.json — never in the repo, so your API key stays out of version control.

Each project keeps its own provider/model in that file, with a shared default the rest inherit — so one machine can drive many projects. Prefer not to store the key at all? Set AETHER_API_KEY in your environment and it overrides whatever's in the config file — handy for CI or shared machines.

/config                     # show current config
 /config gemini              # quick setup — free tier
 /config openai
 /config anthropic
 /config openrouter          # one key, access to many models (incl. free ones)
 /config set <key> <value>   # set a specific field

set keys: provider, model, url (or baseurl), key (or apikey).

/config set model gpt-4o
 /config set key AIza...
 /config set url https://openrouter.ai/api/v1

If you point url at a recognized host (OpenRouter, OpenAI, Anthropic, Gemini), provider is automatically re-synced to match — so the label never drifts from what you're actually calling.

/genesis

/genesis              # analyze the current directory
 /genesis <path>        # analyze a specific directory
 /genesis --force       # regenerate even if .aether/docs already exists

What it does:

1. Scans the entire project — configs, entry points, and every source file that fits the context budget (no arbitrary file-count cap). The default budget is sized for large-context models, so a typical project goes in whole; anything it does have to leave out is listed explicitly, never dropped silently.
2. An AI planning pass decides which docs actually make sense for this project. Always generated: the human guides (getting-started, onboarding), the architecture set (system-overview, folder-structure, tech-stack), and AI_CONTEXT.md. Everything else (contributing, coding-standards, modules, api, business, diagrams, glossary) is only included with real evidence — a frontend or devops project won't get api/endpoints.md just because it's on the list.
3. The AI can also propose a handful of custom docs beyond the fixed catalog when something project-specific deserves its own page (e.g. an unusual build pipeline).
4. Docs are written to .aether/docs/, generated concurrently with retry + backoff on failures, plus a docs/README.md index that links everything.

Each doc is generated from a single shared project context built once before generation starts. If the whole project fits the model's budget, it's sent as real code; when it doesn't, Aether distills the entire project once into factual notes and reuses them for every doc — so nothing is dropped, the expensive pass runs a single time, and all docs stay consistent with each other. Requests stream under the hood with an idle timeout, so a slow model that keeps responding is never cut off mid-answer.

If .aether/docs/ already exists, /genesis won't regenerate it by default — it'll point you to /sync instead. Use --force to fully regenerate anyway.

Tuning the scan budget

The defaults fit most projects into a large-context model without omitting anything. You can open them up further for a very large repo, or tighten them for a small local model, via environment variables:

Two audiences, two contracts

Genesis writes for both people and AI, and they don't get the same treatment:

• Human guides (guides/) lead with the why and explain how the pieces connect. They read like onboarding, not an index. If your repo already has author-written context (a README, CONTEXT.md, …), they lean on it for intent — but you don't have to write anything; they're generated from the code either way.
• AI & architecture docs (AI_CONTEXT.md, architecture/, etc.) stay strict and traceable — every claim maps to a file, so an assistant can trust them without hallucinating.

Both share the same accuracy floor: nothing invented, and a planned feature is never described as already built.

Output structure

.aether/docs/
├── README.md                (always — index of everything below)
├── guides/
│   ├── getting-started.md   (always — install & run, for humans)
│   ├── onboarding.md        (always — mental model & the why)
│   └── contributing.md      (if there's a real contribution process)
├── architecture/
│   ├── system-overview.md   (always)
│   ├── folder-structure.md  (always)
│   ├── tech-stack.md        (always)
│   └── coding-standards.md  (if applicable)
├── modules/overview.md      (if applicable)
├── api/endpoints.md         (only with an actual API/CLI to document)
├── business/rules.md        (if applicable)
├── diagrams/system.md       (if applicable)
├── AI_CONTEXT.md            (always)
├── glossary.md              (if applicable)
└── ...                      (+ custom docs the AI proposes for this project)

/sync

/sync              # sync the current directory
 /sync <path>       # sync a specific directory

Refresh docs after the project changed — without regenerating everything.

How it works:

1. Diffs the project against the last /genesis snapshot (stored in .aether/settings/context.json)
2. Asks the AI which docs are affected by what changed
3. Refreshes only those docs in place — existing sections are patched, nothing is deleted
4. Adds new docs if the changes warrant them (e.g. you added an API layer that didn't exist before)

If no snapshot exists yet, /sync will point you to /genesis first.

Concurrent generation

Both /genesis and /sync generate multiple docs in parallel. The default concurrency is 4; override with:

/clean

/clean              # list all projects and global status
 /clean cache        # remove all cached data (keep configs)
 /clean cache <n>    # remove cache for project #n from the list
 /clean <n>          # remove project #n entirely (config + cache)
 /clean config       # delete ~/.aether/config.json (API keys)
 /clean all          # delete everything in ~/.aether/

Manage global data stored in ~/.aether/. Use /clean with no arguments to see what's stored — all configured projects, their cache sizes, and provider info.

What lives in ~/.aether/

Project storage in the repo

Error Handling & Retries

All API calls retry automatically with exponential backoff:

Rate limits from free tiers (Gemini's 15 RPM, for example) are handled automatically — the CLI waits and retries instead of failing. During generation, each step shows its retry status inline.

Dropdown Navigation

Type / to see all commands. Use ↑↓ arrows to navigate, Enter to select, Tab to autocomplete.

Coming Soon

• /ask — Context-aware Q&A about your codebase
• Dedicated Anthropic provider (currently routed through the OpenAI-compatible client)
• MCP Server — Expose knowledge base to Claude, Cursor, Gemini