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

# User install
curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh

# Remote-only install
curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh -s -- --remote

# For development
moon run cli:install-dev

Quick Start

bash

# Running Sibyl locally? Start it; the CLI points at localhost by default.
sibyl up

# Connecting to a remote or shared server instead? Authenticate first.
sibyl auth login

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

Work tracking

Plan and run tasks, epics, and projects.

Command	Description
`sibyl task`	Task lifecycle management
`sibyl epic`	Deprecated sugar over the task tree; prefer `task --epic`
`sibyl project`	Project management

Sources and synthesis

Ingest external docs and produce source-grounded artifacts.

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

Memory governance

Review, promote, share, and audit memory.

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

System

Auth, organizations, configuration, and operations.

Command	Description
`sibyl auth`	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`	Organizations and member management
`sibyl team`	Teams, membership, and team project access
`sibyl config context`	Server/org/project context bundles (see above)
`sibyl init`	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`	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`	Install local daemon service files
`sibyl docker`	Manage a self-hosted Docker deployment
`sibyl local`	Manage a local Docker-based instance
`sibyl dev`	Devcontainer shell and lifecycle commands
`sibyl update`	Self-update the CLI/containers/skills
`sibyl skill`	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 list-style commands add --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:

An explicit server argument (sibyl auth login https://..., --server)
An explicit context (--context / -C or SIBYL_CONTEXT)
A paired SIBYL_API_URL and SIBYL_AUTH_TOKEN automation environment
The directory-pinned context, then the active context
SIBYL_API_URL without a paired token
[server] url in the legacy config file
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:

--project flag (highest priority)
Path-based project link (from the current directory)
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.

Authentication required

Authentication required
  > sibyl auth login    Log in

Run sibyl auth login 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 --all or -a
Use the global flag --context / -C to override

CLI Reference ​

Installation ​

Quick Start ​

Command Families ​

Memory loop ​

Work tracking ​

Sources and synthesis ​

Memory governance ​

System ​

Global Options ​

Output Formats ​

Environment Variables ​

Configuration ​

Config File Location ​

Config Structure ​

Project Priority ​

Common Patterns ​

AI Agent Integration ​

The Memory Loop ​

Project-Scoped Operations ​

Bulk Operations ​

SilkCircuit Colors ​

Troubleshooting ​

Cannot connect to server ​

Authentication required ​

No project context ​

CLI Reference

Installation

Quick Start

Command Families

Memory loop

Work tracking

Sources and synthesis

Memory governance

System

Global Options

Output Formats

Environment Variables

Configuration

Config File Location

Config Structure

Project Priority

Common Patterns

AI Agent Integration

The Memory Loop

Project-Scoped Operations

Bulk Operations

SilkCircuit Colors

Troubleshooting

Cannot connect to server

Authentication required

No project context