aether — CLI install & reference

Install

Requires Node 18 or newer. Zero runtime dependencies — pure ES modules under the hood.

bash
npm install -g aether-code

That installs the package and registers aether as a global command. After it completes, aether --version should print the current version from any new terminal window.

First-time setup

Run aether with no arguments. If no API key is configured yet, it walks you through getting one:

bash
$ aether

aether — first-time setup
────────────────────────────────────────────────────────────

To use Aether, you need an API key tied to your account.
Keys start with ak_live_.

Step 1: Open https://trynoguard.com/account in your browser.
        ↪ opened it for you.
Step 2: Click Generate API key and copy the key shown.
Step 3: Paste the key below.

API key: ak_live_*****
Verifying... ✓

Setup complete.
Saved to C:\Users\you\.aetherrc (mode 0600).
Plan: PRO · Balance: 8,247 credits

The CLI opens your default browser to https://trynoguard.com/account, prompts you to paste the key, then verifies it against the server before saving. Bad keys are rejected immediately, not on first prompt.

Two modes

Interactive REPL

Run aether with no task argument. Drops you into a Claude-CLI-style prompt:

bash
$ aether

aether  v0.3.0
Aether Core (1M context) · uncensored · review mode  ·  8,247 credits
C:\Users\you\Desktop\my-project

Type /help for shortcuts. /exit or Ctrl+C twice to quit.

> create a hello.txt with a haiku about reverse engineering

Conversation history persists across prompts within the session — the agent remembers what you've already discussed. Type any task, hit enter, watch it work.

One-shot

Run aether "your task". The agent runs to completion, prints results, exits. Good for scripted use, CI, or quick tasks where you don't need a session.

bash
aether "build a TypeScript todo CLI in this folder"
aether --yes "add JSDoc to every exported function in src/"
aether --cwd ./my-project "fix the failing tests"

Subcommands

Command	What it does
aether	Launch interactive REPL (or run setup if no key)
aether "<task>"	One-shot agent run on the task
aether login	Re-run the setup flow (replace existing key)
aether logout	Clear the saved API key
aether balance	Show plan, credit balance, rate-limit headroom
aether config show	Show current config (API key, base URL)
aether config set <key>	Save an API key directly (skip browser flow)
aether config set-base <url>	Override the API base URL (rarely needed)
aether config path	Print path to ~/.aetherrc
aether --help	Show CLI help
aether --version	Print version

Flags

Flag	Effect
--yes	Auto-approve every file write and shell command. Use carefully.
--cwd <path>	Working directory the agent operates in (default: current dir)
--max-turns <n>	Maximum turns per task before stopping (default: 25)
--unsafe-paths	Allow the agent to read/write outside cwd

REPL slash commands

Inside the REPL, lines starting with / are commands instead of prompts:

Command	What it does
/help or ?	Show shortcuts
/exit, /quit, /q	Exit (or press Ctrl+C twice within 1.5s)
/clear	Wipe conversation history. Start fresh.
/balance	Refresh credit balance from server
/cwd	Show current working directory
/cwd <path>	Change working directory
/yes	Toggle auto-approve mode
/turns <n>	Set max turns per prompt (1–200)
/model	Show model info

Tools the agent has

The agent calls these as needed. Read-only tools auto-execute; mutations and shell commands require your approval (unless --yes is set).

read_fileauto

Read any file as UTF-8 text. The agent reads existing code before modifying it.

list_dirauto

List entries in a directory. node_modules, .git, dist are filtered out by default; dotfiles excluded unless requested.

search_filesauto

Recursive regex search across files in a directory. Returns up to 50 matches. Optional glob filter for file names (e.g. *.ts).

write_filey/N approval

Create or overwrite a file. Shows a unified diff before applying — you confirm or decline.

edit_filey/N approval

Replace one occurrence of find with replace. Fails if the find text appears zero or more than one time. Forces precise edits.

run_shelly/N approval

Run a shell command and capture stdout/stderr/exit code. Hard 2-minute timeout. 20 KB output truncation per call so a runaway test suite can't blow up your context.

Safety model

Review by default. Every write_file, edit_file, and run_shell shows what's about to happen and asks y/N. Read-only tools auto-execute.
Path clamping. All file operations are restricted to --cwd by default. The agent can't accidentally write to ~/.ssh or anywhere outside your project. Override with --unsafe-paths only when you truly need it.
Shell timeout. 2-minute hard cap per run_shell call. Long-running test suites either finish in time or get killed.
Output truncation. Tool results over 20 KB are truncated before being sent back to the model. Prevents one bad command from drowning the context window.
API key permissions. Stored at ~/.aetherrc with mode 0600. Never sent anywhere except https://trynoguard.com. Treat it like an SSH key.
Credit reservation. Each turn reserves the worst-case cost up front, refunds the unused portion after. You can never spend more than the reservation per turn.

Recipes

Build a project from scratch

bash
mkdir my-todo && cd my-todo
aether "build a TypeScript CLI that manages a todo list stored in todos.json. Use commander for arg parsing. Set up package.json, tsconfig.json, src/index.ts. Run npm install at the end."

Agent sequence: list dir → npm init -y → write tsconfig.json, src/index.ts → install deps → run build to verify.

Fix failing tests

bash
cd existing-project
aether "run the tests, see what's failing, and fix them"

Agent runs npm test, reads the failing files, makes targeted edits, re-runs tests, repeats until green or it gives up.

Mass refactor

bash
aether --max-turns 40 "convert all CommonJS requires to ES module imports across src/, then update package.json"

Documentation pass

bash
aether --yes "add a one-line JSDoc to every exported function in src/ that doesn't already have one"

--yes is fine here — operation is bounded and additive.

Reverse engineering

bash
aether "deobfuscate ./bundle.min.js, write the cleaned version to ./bundle.clean.js, then identify what the obfuscation was protecting"

Troubleshooting

Error: NO_API_KEY

No key configured. Run aether login to walk through setup, or set the AETHER_API_KEY env var.

Error: INSUFFICIENT_CREDITS

Out of credits. Top up at https://trynoguard.com/pay. Free tier is 150 credits; agentic tasks typically use 30–80 credits per turn.

Error: HTTP_429 — rate limited

You've hit your per-hour rate limit. Wait a minute and try again. FREE = 30/hr, STARTER = 200/hr, PRO = 1000/hr.

Error: HTTP_401 — invalid key

Key was revoked or mistyped. Run aether login to set a fresh one. If you recently rotated keys at https://trynoguard.com/account, the old key in ~/.aetherrc won't work anymore.

Browser didn't auto-open during setup

Open https://trynoguard.com/account manually, generate a key, paste it at the prompt. Auto-open is best-effort and depends on your default-browser association.

The agent keeps asking y/N for every command — can I batch approve?

Yes — toggle auto-approve mode for the session by running /yes in the REPL, or pass --yes on the command line. Use it when you're running scoped, additive tasks where you trust the model's judgment.

The agent went off the rails / wrong direction

Hit Ctrl+C twice in the REPL to exit, then start fresh with /clear or a new session. Pass a more specific task description on the next try. Keep tasks focused — one concrete goal per prompt usually works better than "refactor the whole app".

Where's the conversation log saved?

In the REPL: only in memory for the session. Nothing is persisted server-side either — the agent endpoint is stateless, and credits are the only thing logged. To keep a record, copy/paste from your terminal scrollback or pipe to a file.

Can I use this with my own model / private API?

Override the API base URL: aether config set-base https://your-host. The endpoint shape is OpenAI-compatible tool calling at /api/v1/agent and /api/v1/agent/stream. Self-hosting Aether or pointing at a compatible upstream is supported.

Privacy

The CLI talks only to https://trynoguard.com (configurable via AETHER_BASE_URL). Your prompts, file reads, and shell outputs go to the agent endpoint as part of each turn. Nothing is stored server-side beyond credit accounting — no Conversation rows, no Message rows, no audit log of your actual content.

No telemetry, no analytics, no error reporting from the CLI itself. Source is plain ES modules under aether-code/ in the public repo — read it before you trust it.

`aether` CLI