---
url: /sibyl/cli.md
---
# CLI Reference

The Sibyl CLI (`sibyl`) is a REST client for your knowledge graph and memory loop. It is built for
human users, AI agents, and scripts, with rich terminal output in the SilkCircuit palette and
JSON-first output for automation.

`sibyl` is the client. The server daemon is `sibyld` (serve, worker, db, migrate). This reference
covers the client.

## Installation

```bash
# Connect to a server (macOS)
brew install hyperb1iss/tap/sibyl && sibyl setup https://your-sibyl-host

# Connect to a server (Linux, or anywhere with uv)
uv tool install --upgrade sibyl-dev && sibyl setup https://your-sibyl-host

# Run a local server and web UI instead
curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh

# For development
moon run cli:install-dev
```

[`sibyl setup`](./setup.md) creates the context, signs you in, and installs the skill and the Claude
Code hook. Agents can do the same by following the sentence on the web app's Connect card; see
[Hand It To An Agent](./setup.md#hand-it-to-an-agent).

## Quick Start

```bash
# Connect this machine to a server (no URL: the current configured server; a fresh install
# defaults to localhost:3334)
sibyl setup https://your-sibyl-host

# Link the current directory to a project
sibyl project link <project_id>

# Now commands auto-scope to that project
sibyl task list --status todo
# Load a working context pack for a goal
sibyl context "wire up the password reset endpoint" --intent build
```

## Command Families

The CLI has roughly three dozen command groups. They fall into five families.

### Memory loop

Capture knowledge and recall it back into agent context.

| Command                                | Description                                         |
| -------------------------------------- | --------------------------------------------------- |
| [`sibyl context`](./context.md)        | Recall a compact working context pack for an agent  |
| [`sibyl brief`](./brief.md)            | One-shot lean context brief for a subagent          |
| [`sibyl remember`](./remember.md)      | Remember a decision, plan, idea, claim, or learning |
| [`sibyl reflect`](./reflect.md)        | Reflect raw notes into reviewable memory candidates |
| `sibyl cite`                           | Record citation or misleading-usage feedback        |
| [`sibyl capture`](./capture.md)        | Quick capture with an auto-derived title            |
| [`sibyl note`](./remember.md)          | Add a task note or capture a free note memory       |
| [`sibyl correct`](./memory.md)         | Inspect or correct source memory                    |
| [`sibyl show`](./show.md)              | Show a graph entity or raw memory by ID             |
| [`sibyl entity`](./entity.md)          | Generic entity CRUD operations                      |
| [`sibyl explore`](./explore.md)        | Graph traversal and exploration                     |
| [`sibyl archive`](./archive.md)        | Browse raw quick captures                           |
| [`sibyl session`](./session.md)        | Package a wake-up context bundle                    |
| [`sibyl export`](./export.md)          | Materialize memory into `.sibyl/memory/` files      |
| [`sibyl config context`](./context.md) | Manage named server, org, and project contexts      |

### Work tracking

Plan and run tasks, epics, and projects.

| Command                         | Description                                               |
| ------------------------------- | --------------------------------------------------------- |
| [`sibyl task`](./task-list.md)  | Task lifecycle management                                 |
| [`sibyl epic`](./epic.md)       | Deprecated sugar over the task tree; prefer `task --epic` |
| [`sibyl project`](./project.md) | Project management                                        |

### Sources and synthesis

Ingest external docs and produce source-grounded artifacts.

| Command                             | Description                                                 |
| ----------------------------------- | ----------------------------------------------------------- |
| [`sibyl crawl`](./crawl.md)         | Web crawling and documentation ingestion                    |
| [`sibyl ingest`](./ingest.md)       | Import Claude Code / Codex transcript JSONL into raw memory |
| [`sibyl docs`](./docs.md)           | Import and list document collections                        |
| [`sibyl synthesis`](./synthesis.md) | Source-grounded synthesis (plan/draft/verify)               |

### Memory governance

Review, promote, share, and audit memory.

| Command                                           | Description                                 |
| ------------------------------------------------- | ------------------------------------------- |
| [`sibyl admin memory audit`](./memory.md)         | Inspect memory audit receipts               |
| [`sibyl admin memory inspect`](./memory.md)       | Inspect a memory source and its audit trail |
| [`sibyl admin memory import-status`](./memory.md) | Inspect a source import receipt             |
| [`sibyl admin memory promote`](./memory.md)       | Preview or auto-review candidate promotion  |
| [`sibyl admin memory share`](./memory.md)         | Preview or apply memory sharing             |
| [`sibyl admin memory space`](./memory.md)         | Memory-space inspection and preview         |
| [`sibyl admin memory review`](./memory.md)        | Reflection review queue and dream-cycle     |
| [`sibyl pending-writes`](./pending-writes.md)     | Inspect and replay locally buffered writes  |

### System

Auth, organizations, configuration, and operations.

| Command                         | Description                                          |
| ------------------------------- | ---------------------------------------------------- |
| [`sibyl auth`](./auth.md)       | Authentication, tokens, and API keys                 |
| `sibyl login`                   | Log in to the active or provided server              |
| `sibyl logout`                  | Clear stored auth credentials                        |
| `sibyl whoami`                  | Check auth status for the active context             |
| [`sibyl org`](./org.md)         | Organizations and member management                  |
| [`sibyl team`](./team.md)       | Teams, membership, and team project access           |
| `sibyl config context`          | Server/org/project context bundles (see above)       |
| [`sibyl setup`](./setup.md)     | Connect this machine to a server in one command      |
| [`sibyl init`](./init.md)       | Create a local or remote context for first-run setup |
| `sibyl config`                  | Manage CLI configuration                             |
| `sibyl health`                  | Check Sibyl server health                            |
| `sibyl stats`                   | Show knowledge graph statistics                      |
| `sibyl version`                 | Show version information                             |
| `sibyl logs`                    | View server logs (requires OWNER role)               |
| `sibyl debug`                   | Debug tools for development (requires OWNER role)    |
| [`sibyl doctor`](./doctor.md)   | Diagnose CLI/server/auth/agent setup                 |
| `sibyl up`                      | Start the local server and web UI                    |
| `sibyl down`                    | Stop the local server and web UI                     |
| `sibyl serve`                   | Start the local embedded daemon                      |
| `sibyl start`                   | Start the local embedded daemon in the background    |
| `sibyl stop`                    | Stop the background local daemon                     |
| [`sibyl service`](./service.md) | Install local daemon service files                   |
| [`sibyl docker`](./docker.md)   | Manage a self-hosted Docker deployment               |
| [`sibyl local`](./local.md)     | Manage a local Docker-based instance                 |
| `sibyl dev`                     | Devcontainer shell and lifecycle commands            |
| [`sibyl update`](./update.md)   | Self-update the CLI/containers/skills                |
| [`sibyl skill`](./skill.md)     | Install/list/print version-matched skill packs       |

## Global Options

These options are available on the root command:

```bash
sibyl --context <context_name> <command>         # Override the server/org context
sibyl -C <context_name> <command>                # Short form
sibyl --version                                  # Show CLI version
sibyl -V                                         # Short form
```

### Output Formats

Most commands support a `--json` / `-j` flag for machine-readable output, and every list command
does. The task, project, and entity lists also take `--csv`:

| Option          | Description  | Use Case                              |
| --------------- | ------------ | ------------------------------------- |
| (default)       | Table format | Human-readable terminal output        |
| `--json` / `-j` | JSON output  | Automation, scripting, piping to `jq` |
| `--csv`         | CSV output   | Spreadsheets, data analysis           |

```bash
sibyl task list                              # Table (default)
sibyl task list --json | jq '.[0].name'      # JSON for scripting
sibyl task list --csv > tasks.csv            # CSV export
```

## Environment Variables

| Variable           | Description                       | Example                     |
| ------------------ | --------------------------------- | --------------------------- |
| `SIBYL_CONTEXT`    | Named context (server/org bundle) | `prod`                      |
| `SIBYL_API_URL`    | Server URL (legacy)               | `http://localhost:3334/api` |
| `SIBYL_AUTH_TOKEN` | Auth token (rarely needed)        | `eyJhbG...`                 |

`SIBYL_CONTEXT` names a context created with `sibyl config context create`, not a project ID. A name
with no matching context is a hard error: the command stops instead of quietly running against the
active context, so a typo in a CI variable can never write to the wrong server. Scope a command to a
project with `--project` instead.

API commands select their server in this order:

1. An explicit server argument (`sibyl auth login https://...`, `--server`)
2. An explicit context (`--context` / `-C` or `SIBYL_CONTEXT`)
3. A paired `SIBYL_API_URL` and `SIBYL_AUTH_TOKEN` automation environment
4. The directory-pinned context, then the active context
5. `SIBYL_API_URL` without a paired token
6. `[server] url` in the legacy config file
7. `http://localhost:3334/api`

Authentication commands use the selected context (including a directory pin or the active context)
unless an explicit server is supplied. Specify the server when logging into an automation target.

A paired environment token is used only for its API URL. Selecting a different server uses that
server's stored credentials; a missing login never falls back to the other server's token. A
standalone `SIBYL_AUTH_TOKEN` without `SIBYL_API_URL` applies to the selected server.

For parallel work, select each command's context with `sibyl -C <name> ...` rather than switching
the shared active context. CLI processes coordinate token refresh through the credential file lock.
Authenticate browser automation independently: copying the CLI's rotating refresh token into a
browser cookie lets browser refresh invalidate the CLI's saved token.

## Configuration

### Config File Location

```
~/.sibyl/config.toml
```

### Config Structure

```toml
[server]
url = "http://localhost:3334/api"

[paths]
"/home/user/project-a" = "proj_abc123"
"/home/user/project-b" = "proj_xyz789"

[context]
active = "local"

[contexts.local]
server_url = "http://localhost:3334"
org_slug = ""
default_project = ""

[contexts.prod]
server_url = "https://sibyl.example.com"
org_slug = "myorg"
default_project = "proj_main"
```

### Project Priority

When resolving which project a command scopes to, the CLI checks in this order:

1. `--project` flag (highest priority)
2. Path-based project link (from the current directory)
3. `default_project` on the selected context

`--context` / `-C` and `SIBYL_CONTEXT` select the context, which decides the server and org. The
project comes from the list above.

## Common Patterns

### AI Agent Integration

The CLI is built for AI agent consumption with JSON-first output:

```bash
# Load a context pack and pull titles
sibyl context "implement OAuth2" --json | jq '.items[].title'

# Get task status
sibyl task show <task_id> --json | jq '.metadata.status'

# Filter and process
sibyl task list --status todo --json | jq '[.[] | {id, name, priority}]'
```

### The Memory Loop

```bash
# Load context before starting work
sibyl context "fix the auth token refresh bug" --intent debug

# Capture findings as you go
sibyl capture "Redis WRONGTYPE on refresh was the root cause"

# Reflect a session into reviewable candidates
cat session-notes.md | sibyl reflect --persist --review
```

### Project-Scoped Operations

```bash
# Link once
cd ~/dev/my-project
sibyl project link proj_abc123

# All future commands in this directory are scoped
sibyl task list                      # Only proj_abc123 tasks
sibyl context "work on auth"          # Only loads context from proj_abc123
sibyl task create --title "Fix bug"  # Creates in proj_abc123
```

### Bulk Operations

```bash
# Archive done tasks via stdin
sibyl task list -s done --json | jq -r '.[].id' | sibyl task archive --stdin --yes

# Export tasks to CSV
sibyl task list --csv > backlog.csv
```

## SilkCircuit Colors

The CLI uses the SilkCircuit palette for terminal output:

| Color           | Hex       | Usage                |
| --------------- | --------- | -------------------- |
| Electric Purple | `#e135ff` | Headers, importance  |
| Neon Cyan       | `#80ffea` | Interactions, paths  |
| Coral           | `#ff6ac1` | Data, IDs, secondary |
| Electric Yellow | `#f1fa8c` | Warnings             |
| Success Green   | `#50fa7b` | Success states       |
| Error Red       | `#ff6363` | Errors               |

## Troubleshooting

### Cannot connect to server

```
Cannot connect to Sibyl server
  > Check that the Sibyl server is running
```

Ensure the server is running:

```bash
sibyld serve  # or: moon run dev
```

Writes attempted while offline are buffered locally. Inspect and replay them with
[`sibyl pending-writes`](./pending-writes.md).

### Authentication required

```
Authentication required
  > sibyl auth login    Log in
```

Run [`sibyl auth login`](./auth.md) to authenticate.

### No project context

```
No project specified and no linked project for current directory
```

Either:

* Link the directory: `sibyl project link <project_id>`
* For task/epic commands: pass `--project <project_id>` or `-p`
* For context retrieval: pass `--project <project_id>`, or `--all` to read every accessible project
  on purpose
* Use the global flag `--context` / `-C` to override