Reference

CLI reference

sigil <command> [options]
sigil --help
sigil <command> --help

Running sigil with no arguments starts the daemon and opens the dashboard.

At a glance


Setup	`init` · `update` · `connect` · `uninstall` · `doctor` · `migrate` · `reset`
Memory	`remember` · `ingest` · `search` · `why` · `facts` · `forget` · `docs` · `context` · `export`
Organization	`pod` · `kind` · `session` · `namespace` · `visibility`
Operations	`status` · `maintain` · `daemon` · `register`
Devices	`pair` · `join`

Setup

`init`

sigil init [--url <postgres-url>]

The setup wizard, in the terminal. Drives the same engine as the dashboard and writes everything to ~/.sigil/config.json.

Five steps:

Database — Built-in (PGlite, zero install) · local Postgres · Docker · external URL
LLM provider — Claude Code · OpenRouter · OpenAI · Anthropic · Ollama
Embeddings — OpenAI · Voyage · OpenRouter · Ollama (all pinned to 1024 dimensions)
Coding agents — connect Claude Code, Cursor, Codex CLI, Kiro, Hermes
Your name — stored, and written as your first memory

Flag	Effect
`--url <url>`	Skip the database picker. Creates the database if missing, enables `pgvector`, applies migrations.

Idempotent — re-running preserves existing configuration.

`update`

sigil update [--check] [--force]

Fast-forwards the git clone at ~/.sigil/app to the latest release branch and runs pending migrations. There is no npm package to bump.

Flag	Effect
`--check`	Report whether an update is available; don’t apply it
`--force`	Re-pull and reinstall even if already current

A failed migration rolls the update back rather than leaving you half-upgraded.

`connect`

sigil connect [--clients <a,b,...>] [--all] [--dry-run]

Re-pins the launcher shims in ~/.sigil/bin/ to the current install and re-syncs each client’s generated config — Claude Code hooks and CLAUDE.md, Cursor, Codex CLI, Kiro.

Run this when memory stops working after an upgrade, a reinstall, or a Node version switch. It fixes stale paths without redoing setup, and touches no database, provider, or API key.

Flag	Effect
`--clients <a,b,…>`	Client ids: `claude-code` (`claude`), `cursor`, `codex-cli` (`codex`), `kiro`, `hermes`
`--all`	Reconnect every detected client without prompting
`--dry-run`	Show what would change; write nothing

Non-interactive with --clients/--all, or when stdin isn’t a TTY.

`uninstall`

sigil uninstall [--dry-run]

Removes Sigil’s entries from selected AI clients: MCP entry stripped (other entries preserved), instructions/rules/steering file deleted, hook entries removed for Claude Code.

Your data — ~/.sigil/, the database, stored facts — is not touched. Use reset for that.

`doctor`

sigil doctor [--deep]
sigil doctor --ack

Checks config location and validity, database connection, stored data counts, LLM provider, embedding provider, hook registration, and the hook error budget.

Flag	Effect
`--deep`	Round-trip each connector — actually spawns the MCP server and runs a hook, proving the integration works rather than that its files exist
`--ack`	Acknowledge current hook errors without running checks

Exits non-zero after five unacknowledged hook errors in 24 hours, so CI can catch a degrading install.

`migrate`

sigil migrate

Runs pending database migrations. update does this for you; you need it directly only after restoring a dump.

`reset`

sigil reset               # confirm, then drop the database and wipe everything
sigil reset --yes         # skip the prompt (scripting)
sigil reset --keep-db     # wipe config and disconnect agents, keep the data

Destructive. Export first.

Memory

`remember`

sigil remember "fact" ["fact2" ...]
sigil remember --bg "fact1" "fact2"
echo "a fact" | sigil remember

Saves one or more short, self-contained facts. Each quoted argument is a separate fact; with no arguments, each non-empty line on stdin becomes one.

Flag	Effect
`--bg`	Return immediately; complete the write in a detached process
`--namespace=<ns>`	Target namespace
`--pod=<name>`	Attach to a specific pod instead of the one derived from your working directory

Output reports what AUDM decided: Remembered. (1 new), Already known., or a combination.

`ingest`

sigil ingest <file|url|glob> [options]

sigil ingest ./docs/README.md
sigil ingest "docs/**/*.md"
sigil ingest https://example.com/page --wait
sigil ingest file1.md file2.md --namespace=engineering

Flag	Effect
`--wait`	Block until ingestion finishes and report results. Default is to queue in the background.
`--namespace=<ns>`	Target namespace
`--skip-facts`	Store and embed chunks; extract no facts
`--skip-entities`	Skip entity linking

`search`

sigil search "query" [options]

Flag	Effect
`--limit=<n>`	Max results (default 10)
`--namespace=<ns>`	One namespace, or several comma-separated
`--all-namespaces`	Search every namespace in the store
`--scope`	Restrict to the active project and session pods
`--graph` / `--no-graph`	Expand through the entity graph
`--route`	LLM query routing
`--synthesize`	Return a written answer instead of a list
`--chunks`	Include raw chunk matches

`why`

sigil why "<query>" [--namespace=<ns>] [--limit=5] [--pod-scope=auto|global|<name>,<name>]

Runs the same hybrid search the UserPromptSubmit hook uses and prints the per-fact breakdown — fused RRF score, Hebbian boost, category, importance, confidence, and source pods.

The primary retrieval debugging tool. See Debugging retrieval.

`facts`

sigil facts [--namespace=<ns>] [--category=<c>] [--limit=<n>]

Lists stored facts with their ids. Default limit 20. [VITAL] marks vital importance.

`forget`

sigil forget <id>

Deletes a fact. The id prefix printed by facts or search is enough.

`docs`

sigil docs                 # documents for the current project
sigil docs <uid>           # print one in full
sigil docs --all           # every project

Flag	Effect
`--namespace=<ns>`	Filter by namespace
`--type=<t>`	Filter by source type: `file`, `raw`, `url`, …
`--limit=<n>`	Max documents listed (default 50)
`--max-chars=<n>`	Truncate printed text

`context`

sigil context [--namespace=<ns>] [--limit=<n>] [--explain]

Rebuilds the hot-context snapshot in ~/.sigil/CLAUDE.md. Runs automatically after remember and ingest.

Flag	Effect
`--limit=<n>`	Max facts (default 20)
`--explain`	Don’t write — print which pod kind each fact came from

`export`

sigil export [--format=json|markdown] [--namespace=<ns>] [--output=<path>]

Exports facts, entities, and documents. json by default; markdown for reading. Writes to stdout unless --output is given.

Organization

`pod`

sigil pod list [--type=<t>] [--namespace=<ns>] [--limit=20]
sigil pod show <uid>
sigil pod create --type=person --name="<name>" [options]
sigil pod archive <uid>
sigil pod delete <uid> --confirm

create supports --type=person today. Session and project pods are created automatically.

Person options: --slack=U123 · --github=<username> · --email=<addr> · --role="…" · --relationship=manager|report|peer|external · --notes="…" · --namespace=<ns>

`kind`

sigil kind list
sigil kind show <name>

Inspect registered pod kinds and their contracts. See Pod kinds.

`session`

sigil session current           # active session uid + summary
sigil session list [--limit=10]
sigil session show [<uid>]      # defaults to the active session

`namespace`

sigil namespace list
sigil namespace delete <ns> [--confirm]

`visibility`

sigil visibility <fact-id|uid> <shared|agent|device>

Scope	Who can retrieve it
`shared`	Every device and every agent — the default
`agent`	Only the agent that wrote it
`device`	Only the machine that wrote it

Takes effect on the next read, on every device. See Provenance and visibility.

Operations

`status`

sigil status [--namespace=<ns>]

Knowledge base statistics — documents, chunks, facts, entities, relations, and lifecycle stage distribution.

`maintain`

sigil maintain

Periodic memory maintenance: promote eligible fresh facts, close editing windows, consolidate graph edges. Monthly is plenty. See Memory decay.

`daemon`

sigil daemon start [--foreground]
sigil daemon stop
sigil daemon restart
sigil daemon status
sigil daemon logs [--follow]
sigil daemon open              # open the dashboard
sigil daemon url               # print the URL with its auth token

The daemon auto-starts on first use; these are for explicit control.

File
`~/.sigil/sock`	Unix socket
`~/.sigil/sigild.pid`	PID file
`~/.sigil/sigild.log`	Append-only log

`register`

sigil register [--http] [--print]

Registers the MCP server. By default a stable stdio launcher at ~/.sigil/bin/sigil-mcp — because the registration points at a shim rather than a versioned path, it survives Node switches and reinstalls.

Flag	Effect
`--http`	Register the daemon’s HTTP transport instead (`/mcp` + bearer token). The URL never changes.
`--print`	Print the config without modifying any files

Devices

`pair`

sigil pair create --name <device-name> [--role <role>] [--ns ns1,ns2] [--ttl <seconds>]
sigil pair list
sigil pair revoke <id>

Run on the master. Prints a plaintext code once, which is never stored.

Role	Grants
`reader`	Read-only — search, status
`writer`	Read and write — remember, ingest (default)
`admin`	Full access, including device management

`join`

sigil join <master-node-id> <pairing-code> [--name <name>]
           [--addresses host:port,host:port] [--relay <url>] [--lite]

Run on the joining device. Iroh resolves the master’s transport details automatically; --addresses and --relay override that. --lite joins as a lite-follower that proxies everything and stores nothing locally.

See Multi-device.

Exit codes

Code	Meaning
`0`	Success
`1`	Command error, or `doctor` found five or more unacknowledged hook errors

Environment

Configuration lives in config.json, not the environment. The only variables Sigil reads are ones that cannot live in a file:

Variable	Purpose
`HOME`	Locates `~/.sigil/`
`SIGIL_PGLITE_PATH`	Redirect the embedded database path (tests, launch)
`SIGIL_BRANCH`	Release-lane selector, set by `install.sh`
`SIGIL_DEBUG`	Verbose diagnostics
`SIGIL_AGENT`, `SIGIL_WORKER_ID`, `SIGIL_SOURCE`, `SIGIL_DAEMON_PROCESS`, `SIGIL_SUPERVISED`	Per-process identity and IPC — set by Sigil itself

A stray LLM_PROVIDER or DATABASE_URL in your shell has no effect. That’s deliberate: it used to be possible for a global env var to silently override what onboarding saved.