Aetheel/docs/commands.md

# Aetheel Commands Reference

All commands work across every adapter (Slack, Discord, Telegram, WebChat).

## Chat Commands

Type these as regular messages in any channel or DM. No `/` prefix needed — just send the word as a message. The `/` prefix also works in DMs and on platforms that don't intercept it (Discord, Telegram, WebChat).

> In Slack channels, Slack intercepts `/` as a native slash command and blocks it. Use the prefix-free form instead (e.g. `engine claude` not `/engine claude`). In Slack DMs with the bot, both forms work.

### General

| Command | Description |
|---|---|
| `status` | Show bot status, engine, model, sessions |
| `help` | Show all available commands |
| `time` | Current server time |
| `sessions` | Active session count + cleanup stale |
| `reload` | Reload config.json and skills |
| `subagents` | List active background tasks |

### Runtime Switching (live, no restart needed)

| Command | Description |
|---|---|
| `engine` | Show current engine (opencode/claude) |
| `engine opencode` | Switch to OpenCode runtime |
| `engine claude` | Switch to Claude Code runtime |
| `model` | Show current model |
| `model <name>` | Switch model (e.g. `model anthropic/claude-sonnet-4-20250514`) |
| `provider` | Show current provider (OpenCode only) |
| `provider <name>` | Switch provider (e.g. `provider anthropic`, `provider openai`) |
| `usage` | Show LLM usage stats, costs, and rate limit history |

Engine, model, and provider changes take effect immediately and are persisted to `config.json` so they survive restarts.

#### Examples

```
engine claude
model claude-sonnet-4-20250514

engine opencode
model anthropic/claude-sonnet-4-20250514
provider anthropic

model openai/gpt-4o
provider openai

model google/gemini-2.5-pro
provider google
```

### Configuration

| Command | Description |
|---|---|
| `config` | Show config summary (engine, model, adapters) |
| `config show` | Dump full config.json |
| `config set <key> <value>` | Edit a config value (dotted notation) |

#### Config Set Examples

```
config set runtime.timeout_seconds 300
config set claude.max_turns 5
config set webchat.enabled true
config set discord.enabled true
config set webhooks.token my-secret-token
config set heartbeat.silent true
```

After `config set`, run `reload` to apply changes that don't auto-apply (adapter changes require a restart).

### Scheduler

| Command | Description |
|---|---|
| `cron list` | List all scheduled jobs |
| `cron remove <id>` | Remove a scheduled job by ID |

### MCP Servers

| Command | Description |
|---|---|
| `mcp list` | List configured MCP servers |
| `mcp add <name> <command> [args]` | Add a new MCP server |
| `mcp remove <name>` | Remove an MCP server |

Examples:

```
mcp add brave-search uvx brave-search-mcp@latest
mcp add filesystem npx @anthropic-ai/mcp-filesystem /home/user/projects
mcp add github uvx github-mcp-server
mcp remove brave-search
```

### Skills

| Command | Description |
|---|---|
| `skill list` | List all loaded skills |
| `skill show <name>` | View a skill's content |
| `skill create <name>` | Create a new skill template |
| `skill rename <old> <new>` | Rename a skill |
| `skill remove <name>` | Remove a skill |
| `skill reload` | Reload all skills |

You can also manage skills via natural language:

| Natural Language | What It Does |
|---|---|
| "Create a skill for checking weather" | Creates a skill with auto-derived name and triggers |
| "Rename my-old-skill to weather" | Renames the skill directory and updates SKILL.md |

These are handled locally (no AI call needed), so they work even if the AI runtime is down.

### AI Chat

Any message that isn't a command is sent to the AI. The AI can also trigger actions by including tags in its response:

| AI Action Tag | What It Does |
|---|---|
| `[ACTION:remind\|<minutes>\|<message>]` | Schedule a one-shot reminder |
| `[ACTION:cron\|<cron_expr>\|<prompt>]` | Schedule a recurring cron job |
| `[ACTION:spawn\|<task>]` | Spawn a background subagent |

---

## Terminal Commands

After installation, the `aetheel` command is available in your shell.

### Service Management

| Command | Description |
|---|---|
| `aetheel start` | Start Aetheel in the foreground |
| `aetheel stop` | Stop the background service |
| `aetheel restart` | Restart the background service |
| `aetheel status` | Show install and service status |
| `aetheel logs` | Tail the live log file |

### Setup & Maintenance

| Command | Description |
|---|---|
| `aetheel setup` | Re-run the interactive setup wizard |
| `aetheel update` | Pull latest code + update dependencies |
| `aetheel doctor` | Run diagnostics (config, tokens, runtimes) |
| `aetheel config` | Open config.json in your `$EDITOR` |

### Pass-Through

Any other arguments are passed directly to `main.py`:

```bash
aetheel --test              # Echo mode, no AI
aetheel --claude            # Override: use Claude engine
aetheel --model gpt-4o      # Override: specific model
aetheel --log DEBUG          # Override: debug logging
```

These flags are optional overrides. All settings come from `~/.aetheel/config.json` by default.

---

## Config File Reference

All features are controlled by `~/.aetheel/config.json`. No flags required.

```jsonc
{
  "runtime": {
    "engine": "opencode",       // "opencode" or "claude"
    "mode": "cli",              // "cli" or "sdk"
    "model": null,              // e.g. "anthropic/claude-sonnet-4-20250514"
    "provider": null,           // e.g. "anthropic", "openai", "google"
    "timeout_seconds": 120
  },
  "claude": {
    "model": null,              // e.g. "claude-sonnet-4-20250514"
    "max_turns": 3,
    "no_tools": false
  },
  "slack":    { "enabled": true },
  "telegram": { "enabled": false },
  "discord":  { "enabled": false, "listen_channels": [] },
  "webchat":  { "enabled": false, "port": 8080 },
  "webhooks": { "enabled": false, "port": 8090, "token": "" },
  "heartbeat": { "enabled": true },
  "hooks":    { "enabled": true }
}
```

Adapters auto-enable when their token is set in `.env`, even if `enabled` is `false` in config.

---

## Auto-Failover & Rate Limit Handling

When a rate limit or quota error is detected from the active engine:

1. Aetheel notifies you in the channel with the error details
2. Automatically attempts to failover to the other engine (claude → opencode or vice versa)
3. If failover succeeds, the response is delivered and the active engine is switched
4. If failover also fails, both errors are reported

Rate limit detection covers: HTTP 429, "rate limit", "quota exceeded", "too many requests", "usage limit", "credit balance", "overloaded", and similar patterns from both Claude Code and OpenCode.

Use `usage` to see cumulative stats including rate limit hits and failover count.

Note: Claude Code's `--output-format json` returns `cost_usd` per request. OpenCode does not currently expose per-request cost in its CLI output, so cost tracking is only available for the Claude engine.