Claude
Skill
cli
Imported from hyperb1iss/sibyl/docs/cli.
Virus-scanned
Reviewed automatically before listing.
Download
hyperb1iss-sibyl-docs_cli-c59f48c.zip · 67 KB
Install
skills CLI
npx skills add https://github.com/hyperb1iss/sibyl/tree/main/docs/cli
Claude Code
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install hyperb1iss-sibyl@llmmart
Git
git clone https://github.com/hyperb1iss/sibyl.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole hyperb1iss/sibyl collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
skill
Install the loader skill and print bundled markdown packs. skill manages the Sibyl skill stub that
Claude Code, Codex, and other assistants load to learn the memory loop, and it prints
version-matched markdown packs straight from the installed CLI bundle.
Called with no subcommand, skill prints the canonical loader markdown to stdout. Pass --install
to write it into your assistant skill roots instead.
Synopsis
sibyl skill [options]
sibyl skill <command> [options]
Options
| Option | Short | Default | Description |
|---|---|---|---|
--install |
false | Install the loader skill into assistant skill roots | |
--force |
false | Replace existing symlink or non-directory skill targets | |
--quiet |
-q |
false | Suppress install status output |
Commands
| Command | Description |
|---|---|
sibyl skill install |
Install the stable Sibyl skill stub into skill roots |
sibyl skill list |
List skill packs available from this CLI version |
sibyl skill get |
Print a version-matched markdown skill pack |
Skill roots are ~/.claude/skills, ~/.codex/skills, and ~/.agents/skills.
skill install
Install the stable Sibyl skill stub into assistant skill roots.
sibyl skill install [options]
| Option | Short | Default | Description |
|---|---|---|---|
--force |
false | Replace existing symlink or non-directory skill targets | |
--quiet |
-q |
false | Suppress install status output |
Example
sibyl skill install --force
skill list
List the skill packs bundled with this installed CLI version.
sibyl skill list
Packs include core, quick, workflows, examples, and migration.
skill get
Print a version-matched markdown skill pack from the CLI bundle. Defaults to the core pack.
sibyl skill get [name]
| Argument | Required | Default | Description |
|---|---|---|---|
name |
No | core |
Skill pack to print (sibyl skill list for choices) |
Examples
# Print the core workflow pack
sibyl skill get
# Print the minimal subagent pack
sibyl skill get quick
Notes
- The stub is intentionally stable: it points assistants at the version-matched packs rather than embedding the full contract, so a CLI upgrade refreshes guidance without re-installing.
--forcereplaces existing symlinks or non-directory targets; without it, those roots are skipped.sibyl doctorchecks that the installed stub matches the canonical markdown and flags stale copies.
Related Commands
sibyl doctor- Verify the skill stub is installed and currentsibyl update- Refresh skills as part of a self-updatesibyl local- Install skills and hooks together withlocal setup
Files (sibyl)
-
add.md 1.3 KB
# add `add` is a hidden compatibility alias for [`sibyl remember`](./remember.md). New instructions and automation should use `remember`, which preserves the raw source before graph projection. ```bash sibyl remember "JWT refresh failure" \ "Redis TTL expiry leaves a stale token key; regenerate on WRONGTYPE." \ --kind error_pattern --domain auth ``` ## Compatibility The alias accepts the `remember` grammar: ```bash sibyl add "JWT refresh failure" \ "Redis TTL expiry leaves a stale token key; regenerate on WRONGTYPE." \ --kind error_pattern ``` The hidden legacy `--type` spelling remains accepted for migration, but `--kind` is canonical. Old graph-add flags such as `--title`, `--category`, `--language`, and `--skip-conflicts` are not part of the agent contract. Use the advertised kinds `episode`, `decision`, `procedure`, `error_pattern`, `rule`, `plan`, `idea`, `claim`, `artifact`, `session`, and `note`. Run `sibyl remember --help` for compatibility kinds and the complete option set. ## Related Commands - [`sibyl remember`](./remember.md) - Store durable raw-first memory - [`sibyl capture`](./capture.md) - Quick capture with an auto-derived title - [`sibyl context`](./context.md) - Load existing project memory before writing - [`sibyl correct`](./memory.md) - Inspect or correct source memory -
archive.md 1.1 KB
# Archive Browse the raw archive created by quick memory capture. This is the write-once sidecar that keeps the original payload before graph extraction reshapes it. ## Usage ```bash sibyl archive list sibyl archive list --surface dashboard sibyl archive show <capture_id> ``` ## Commands ### `sibyl archive list` List archived raw captures for the current organization. Page through results with `--limit` / `-n` (default 20) and `--offset` (skip the first N results). ```bash sibyl archive list --limit 20 sibyl archive list --limit 20 --offset 20 sibyl archive list --type pattern sibyl archive list --surface cli ``` ### `sibyl archive show` Show one archived raw capture with verbatim content. ```bash sibyl archive show 7f7b4b91-1cd8-47c5-a03e-59e2df96e6d0 ``` ## Notes - The archive is populated by quick capture flows that send `metadata.capture_mode=quick`. - `list` shows summaries; `show` returns the full raw content. ## Related Commands - [`sibyl capture`](./capture.md) - Quick capture that feeds the archive - [`sibyl remember`](./remember.md) - Typed memory-loop writes - [Memory governance](./memory.md) - Inspect and audit raw memory sources -
auth.md 7.7 KB
# auth Authentication and credentials. `auth` logs the CLI into a Sibyl server, manages stored tokens, and creates API keys for MCP clients and scripts. Top-level aliases are available for the common path: `sibyl login`, `sibyl logout`, and `sibyl whoami`. ## Commands | Command | Description | | ----------------------------------------------- | ---------------------------------------- | | [`sibyl auth login`](#auth-login) | Log in to a server and save credentials | | [`sibyl auth status`](#auth-status) | Show auth status for the current context | | [`sibyl auth local-signup`](#auth-local-signup) | Create a local user and save its token | | [`sibyl auth set-token`](#auth-set-token) | Set an auth token for a server | | [`sibyl auth clear-token`](#auth-clear-token) | Clear auth tokens for a server | | [`sibyl auth api-key`](#auth-api-key) | API key management | --- ## auth login Login to a Sibyl server and save credentials. With no URL, logs in to the active context or the default server. Login opens a browser for the auth flow unless `--no-browser` is set, or you can pass `--email` and `--password` for local login. The default self-hosted install uses local auth. Explicit `--email` and `--password` credentials go to the local login path; browser login is for device/OAuth/OIDC flows configured on the server. ### Synopsis ```bash sibyl auth login [url] [options] # Alias: sibyl login [url] [options] ``` ### Arguments | Argument | Required | Description | | -------- | -------- | ---------------------------------------------------------- | | `url` | No | Server URL. If omitted, uses the active context or default | ### Options | Option | Short | Default | Description | | ---------------------- | ----- | ------- | ------------------------------------------------ | | `--server` | `-s` | (none) | Server base URL (alias for the positional URL) | | `--context` | `-c` | (none) | Create or update a named context for this server | | `--no-browser` | | false | Print the URL instead of opening a browser | | `--timeout` | | 180 | Seconds to wait for approval/auth | | `--email` | `-e` | (none) | Email for local login | | `--password` | `-p` | (none) | Password for local login | | `--break-glass-reason` | | (none) | Incident reason for emergency local login | | `--insecure` | `-k` | false | Disable SSL certificate verification | ### Examples ```bash # Log in to the active context or default server sibyl login # Log in to a specific server sibyl login https://sibyl.example.com # Log in and create a named context in one step sibyl auth login https://prod.example.com -c prod # Headless login (no browser) sibyl auth login --no-browser # Local email/password login sibyl auth login -e stef@example.com -p "$SIBYL_PASSWORD" # Emergency local login during an approved break-glass window sibyl auth login \ -e owner@example.com \ -p "$SIBYL_BREAK_GLASS_PASSWORD" \ --break-glass-reason "INC-123 IdP outage" ``` --- ## auth status Show auth status for the current context. ```bash sibyl auth status ``` --- ## auth local-signup Create a local user and save the returned access token. On a fresh default install, this is allowed for setup bootstrap and creates the first owner/admin user. After setup completes, local signup is blocked unless the request uses an invitation token or public signups are explicitly enabled on the server. ### Synopsis ```bash sibyl auth local-signup --email <email> --password <password> --name <name> ``` ### Options | Option | Short | Required | Description | | ------------ | ----- | -------- | ---------------------- | | `--email` | `-e` | Yes | Email address | | `--password` | `-p` | Yes | Password (min 8 chars) | | `--name` | `-n` | Yes | Display name | ### Example ```bash sibyl auth local-signup \ -e dev@localhost -p "devpassword" -n "Dev User" ``` --- ## auth set-token Set an auth token for a server directly. Defaults to the active context server. ### Synopsis ```bash sibyl auth set-token <token> [options] ``` ### Arguments | Argument | Required | Description | | -------- | -------- | ----------- | | `token` | Yes | Auth token | ### Options | Option | Short | Description | | ---------- | ----- | ------------------------------------------------------------ | | `--server` | `-s` | Server URL to set the token for (defaults to active context) | --- ## auth clear-token Clear auth tokens for a server. Defaults to the active context server, or use `--all` to clear every stored token. ### Synopsis ```bash sibyl auth clear-token [options] ``` ### Options | Option | Short | Description | | ---------- | ----- | ----------------------------------------------------------- | | `--server` | `-s` | Server URL to clear tokens for (defaults to active context) | | `--all` | `-a` | Clear tokens for ALL servers | ### Example ```bash sibyl auth clear-token --all ``` --- ## auth api-key API key management. API keys authenticate MCP clients and scripts without a browser session. Keys carry scopes and can be limited to specific projects and memory spaces. | Subcommand | Description | | --------------------------- | ----------------- | | `sibyl auth api-key list` | List API keys | | `sibyl auth api-key create` | Create an API key | | `sibyl auth api-key revoke` | Revoke an API key | ### auth api-key list ```bash sibyl auth api-key list ``` ### auth api-key create ```bash sibyl auth api-key create --name <name> [options] ``` | Option | Short | Default | Description | | ------------------- | ----- | ------- | ---------------------------------------------------- | | `--name` | `-n` | (req.) | Display name for the key (required) | | `--live` / `--test` | | `live` | Use an `sk_live_` (default) or `sk_test_` key prefix | | `--scopes` | | `mcp` | Comma-separated scopes | | `--projects` | | (none) | Comma-separated graph project IDs the key may access | | `--memory-spaces` | | (none) | Comma-separated memory-space IDs the key may access | | `--expires-days` | | (none) | Optional expiry in days (1-365) | Available scopes include `mcp`, `api:read`, `api:write`, plus memory scopes. The full key value is shown only once at creation. #### Examples ```bash # MCP key for a single project sibyl auth api-key create --name "claude-mcp" --projects proj_abc123 # Read-only API key that expires in 90 days sibyl auth api-key create --name "ci-readonly" \ --scopes "api:read" --expires-days 90 # Test key scoped to a memory space sibyl auth api-key create --name "agent-sandbox" --test \ --memory-spaces space_main ``` ### auth api-key revoke ```bash sibyl auth api-key revoke <api_key_id> ``` | Argument | Required | Description | | ------------ | -------- | -------------------- | | `api_key_id` | Yes | API key ID to revoke | ## Related Commands - [`sibyl config context`](./context.md) - Manage server/org/project contexts - [`sibyl org`](./org.md) - Organization and member management -
brief.md 1.8 KB
# brief One-shot lean context brief for injecting into a subagent prompt. `brief` is a stripped-down sibling of [`sibyl context`](./context.md): given a goal, it prints wake-layer markdown only, with no skill ceremony, no related-graph expansion, and no JSON envelope. Pipe or paste the output straight into a worker agent's prompt. ## Synopsis ```bash sibyl brief <goal> [options] ``` ## Arguments | Argument | Required | Description | | -------- | -------- | --------------------- | | `goal` | Yes | Subagent goal or task | ## Options | Option | Short | Default | Description | | ----------- | ----- | ------- | ---------------------------------------------- | | `--intent` | `-i` | `build` | Agent intent (see [`context`](./context.md)) | | `--project` | `-p` | (auto) | Project ID | | `--all` | `-a` | false | Use all accessible projects | | `--budget` | | 1500 | Token budget for the rendered brief (100-8000) | ## Examples ```bash # Lean brief for a worker agent sibyl brief "implement the password reset endpoint" # Bias toward debugging context with a smaller budget sibyl brief "auth token refresh fails intermittently" --intent debug --budget 800 # Inject straight into a subagent prompt PACK=$(sibyl brief "wire up OAuth2") ``` ## Notes - `brief` always uses the `wake` layer with related-graph expansion off, so it is faster and leaner than `context`. Reach for `context` when you need a deeper pack, raw memories, a diary, or JSON. - The project resolves from the current directory unless you pass `--project` or `--all`. ## Related Commands - [`sibyl context`](./context.md) - Full working context pack with more layers and options - [`sibyl session`](./session.md) - Wake-up bundle for a new session -
capture.md 3.4 KB
# capture Capture a quick memory without separate title and content fields. `capture` is the fastest way into the memory loop: pass a single blob of text (or pipe it in) and Sibyl derives a title for you. ## Synopsis ```bash sibyl capture [content] [options] ``` Content is read from stdin when the positional argument is omitted. ## Arguments | Argument | Required | Description | | --------- | -------- | --------------------------------------- | | `content` | No | What to capture. Reads stdin if omitted | ## Options | Option | Short | Default | Description | | ------------------- | ----- | --------- | -------------------------------------------------------- | | `--title` | `-t` | (derived) | Optional title. Derived from content when omitted | | `--type` | | `episode` | Entity type to create (see [entity](./entity.md)) | | `--tags` | | (none) | Comma-separated tags | | `--project` | `-p` | (auto) | Project ID | | `--all-projects` | | false | Do not auto-scope to the linked project | | `--related-to` | | (none) | Comma-separated entity IDs to connect with `RELATED_TO` | | `--task` | | (none) | Comma-separated task IDs to connect with `RELATED_TO` | | `--active-task` | | on | Auto-link to the single active task (`--no-active-task`) | | `--content-file` | | (none) | Read content from a file | | `--max-size` | | 1048576 | Maximum content file size in bytes | | `--follow-symlinks` | | false | Allow `--content-file` to read through symlinks | | `--wait-searchable` | | false | Wait until the entity is persisted and retrievable | | `--json` | `-j` | false | Output as JSON | ## When to Use Reach for `capture` when you have a thought to record and do not want to stop to phrase a title. Use [`remember`](./remember.md) when the memory has a clear name or a specific kind (decision, plan, claim). Use [`add`](./add.md) when you want explicit title and content fields. ## Examples ### Quick Capture ```bash sibyl capture "PgBouncer transaction mode fixed the connection timeout under load" ``` ### Pipe Content In ```bash echo "Remember to backfill embeddings after the cutover" | sibyl capture ``` ### Capture with a Type and Tags ```bash sibyl capture "Always clone the Surreal driver per org before writing" \ --type pattern --tags "surreal,concurrency" ``` ### Capture from a File ```bash sibyl capture --content-file ./scratch-notes.md --type episode ``` ### Link to the Active Task When a task is in `doing`, captures auto-link to it. Disable with `--no-active-task`: ```bash sibyl capture "Found the root cause in the token refresh path" sibyl capture "Unrelated idea for the docs site" --no-active-task ``` ## Related Commands - [`sibyl remember`](./remember.md) - Capture a titled, typed memory - [`sibyl note`](./remember.md) - Add a task note or free note memory - [`sibyl remember`](./remember.md) - Add knowledge with explicit title and content - [`sibyl archive`](./archive.md) - Browse raw quick captures -
context.md 17 KB
# Context and Context Configuration `sibyl context` recalls agent-ready working memory for a goal. Named CLI contexts bundle server URL, organization, and project settings under `sibyl config context`. ## Overview A context contains: - **Server URL**: Where the Sibyl API is running - **Organization**: Which org to use (optional) - **Default Project**: Fallback project for operations - **Insecure**: Whether to skip SSL verification ## Commands - `sibyl context <goal>` - Compile a context pack for an agent - `sibyl config context` - Show current CLI context - `sibyl config context pack` - Compile a context pack via the config group - `sibyl config context list` - List all contexts - `sibyl config context show` - Show context details - `sibyl config context create` - Create a context - `sibyl config context use` - Set active context - `sibyl config context link` - Pin a directory tree to a context - `sibyl config context unlink` - Remove a directory's context pin - `sibyl config context update` - Update a context - `sibyl config context delete` - Delete a context - `sibyl config context clear` - Clear active context --- ## config context (no subcommand) Show the current active context. ### Synopsis ```bash sibyl config context [options] ``` ### Options | Option | Short | Description | | ------------------------ | ----- | ---------------------------------------------- | | `--json` | `-j` | JSON output | | `--quick` / `--validate` | | Show local server/org/project/auth status only | ### Example ```bash sibyl config context ``` Output: ``` Context: local (active) Server: http://localhost:3334 Org: auto Project: proj_abc123 (linked) ``` If a directory is linked, it shows `(linked)` next to the project. Use `--quick` for a fast local status check that skips fetching full project detail. --- ## context Compile a precise context pack for an agent. The hidden `search` and `recall` compatibility aliases route here too; new instructions should use `context`. ### Synopsis ```bash sibyl context <goal> [options] ``` ### Arguments | Argument | Required | Description | | -------- | -------- | ----------------------- | | `goal` | Yes | Agent goal or user task | ### Options | Option | Short | Default | Description | | ----------- | ----- | -------- | ------------------------------------------------ | | `--intent` | `-i` | `build` | `build`, `plan`, `review`, `debug`, or `general` | | `--layer` | | `recall` | `wake`, `recall`, or `deep_search` | | `--domain` | `-d` | (none) | Domain/category to bias retrieval | | `--project` | `-p` | (auto) | Project ID to scope context | | `--agent` | | (none) | Agent diary identity to include | | `--all` | `-a` | false | Use all accessible projects | | `--limit` | `-l` | 12 | Maximum context items (1-50) | | `--related` | | on | Include one-hop related graph context | | `--audit` | | false | Include full retrieval metadata | | `--budget` | | (none) | Approximate Markdown token budget | | `--json` | `-j` | false | JSON output | ### Raw-Memory Filters These flags switch recall to verbatim raw memory and narrow which raw imports qualify: | Option | Default | Description | | ------------------- | --------- | ---------------------------------------------------- | | `--raw` | false | Recall verbatim raw memories | | `--diary` | false | Recall a private agent diary | | `--scope` | `private` | Memory scope: `private`, `project`, `team`, or `org` | | `--scope-key` | (none) | Project/team/shared scope key | | `--participant` | (none) | Filter raw imports by participant | | `--label` | (none) | Filter raw imports by adapter label | | `--thread` | (none) | Filter raw imports by thread | | `--occurred-after` | (none) | Filter raw imports after an ISO timestamp | | `--occurred-before` | (none) | Filter raw imports before an ISO timestamp | | `--as-of` | (none) | Filter raw memory by validity timestamp | ### Examples ```bash # Compile a context pack for a goal sibyl context "implement the password reset endpoint" # Markdown output for direct agent injection sibyl context "debug the auth refresh bug" --intent debug # Deep search with a wider item budget sibyl context "how synthesis verification works" \ --layer deep_search --limit 40 # Verbatim raw memories from a team scope, time-bounded sibyl context "auth outage timeline" \ --raw --scope team --scope-key platform --occurred-after 2026-07-01 ``` --- ## config context pack Compile a precise context pack for an agent from the config group. Same compiler as `sibyl context`, with pack-tuning flags and a wider intent list. ### Synopsis ```bash sibyl config context pack <goal> [options] ``` ### Arguments | Argument | Required | Description | | -------- | -------- | ----------------------- | | `goal` | Yes | Agent goal or user task | ### Options | Option | Short | Default | Description | | ----------------- | ----- | -------- | ---------------------------------------------------------------------------- | | `--intent` | `-i` | `build` | `build`, `plan`, `ideate`, `research`, `debug`, `decide`, `learn`, `general` | | `--layer` | | `recall` | `wake`, `recall`, or `deep_search` | | `--domain` | `-d` | (none) | Domain/category to bias retrieval | | `--project` | `-p` | (auto) | Project ID to scope context | | `--agent` | | (none) | Agent diary identity to include | | `--all` | `-a` | false | Use all accessible projects | | `--limit` | `-l` | 24 | Maximum total context items (1-50) | | `--related` | | on | Include one-hop related graph context | | `--related-limit` | | 3 | Related items per context item (0-5) | | `--markdown` | `-m` | false | Output compact Markdown for agent injection | | `--audit` | | false | Include full retrieval metadata | | `--budget` | | (none) | Approximate Markdown token budget | | `--json` | `-j` | false | JSON output | ### Example ```bash sibyl config context pack "plan the retrieval refactor" --intent plan --markdown ``` --- ## config context list List all configured contexts. ### Synopsis ```bash sibyl config context list [options] ``` ### Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | ### Example ```bash sibyl config context list ``` Output: ``` Contexts Name Server Org Project ─────────────────────────────────────────────────────────────────── * local http://localhost:3334 auto none staging https://staging.sibyl.io myorg proj_staging prod https://sibyl.example.com myorg proj_main * = active context ``` --- ## config context show Show details of a specific context. ### Synopsis ```bash sibyl config context show [name] [options] ``` ### Arguments | Argument | Required | Description | | -------- | -------- | --------------------------------- | | `name` | No | Context name (defaults to active) | ### Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | ### Example ```bash sibyl config context show prod ``` Output: ``` Context: prod Server: https://sibyl.example.com Org: myorg Project: proj_main ``` --- ## config context create Create a new context. ### Synopsis ```bash sibyl config context create <name> [options] ``` ### Arguments | Argument | Required | Description | | -------- | -------- | ------------------------------------ | | `name` | Yes | Context name (e.g., 'prod', 'local') | ### Options | Option | Short | Default | Description | | ------------ | ----- | ----------------------- | --------------------- | | `--server` | `-s` | `http://localhost:3334` | Server URL | | `--org` | `-o` | (auto) | Organization slug | | `--project` | `-p` | (none) | Default project ID | | `--use` | `-u` | false | Set as active context | | `--insecure` | `-k` | false | Skip SSL verification | | `--json` | `-j` | false | JSON output | ### Examples ```bash # Create local development context sibyl config context create local --server http://localhost:3334 # Create production context and activate it sibyl config context create prod \ --server https://sibyl.example.com \ --org myorg \ --project proj_main \ --use # Create staging with self-signed cert sibyl config context create staging \ --server https://staging.internal:3334 \ --insecure ``` Output: ``` Created context 'prod' Set as active context Server: https://sibyl.example.com Org: myorg Project: proj_main ``` --- ## config context use Set the active context. This affects all subsequent commands. ### Synopsis ```bash sibyl config context use <name> [options] ``` ### Arguments | Argument | Required | Description | | -------- | -------- | ------------------------ | | `name` | Yes | Context name to activate | ### Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | ### Example ```bash sibyl config context use prod ``` Output: ``` Switched to context 'prod' Server: https://sibyl.example.com ``` --- ## config context link Pin a directory tree to a context so commands run there route to its server. Unlike `sibyl project link`, this binds only the context (server/org), not a project, so new repositories under the tree route to the right server before they are linked to a specific project. ### Synopsis ```bash sibyl config context link <name> [options] ``` ### Arguments | Argument | Required | Description | | -------- | -------- | ------------------------------------- | | `name` | Yes | Context name to pin to this directory | ### Options | Option | Short | Default | Description | | -------- | ----- | ------- | -------------- | | `--path` | `-p` | (cwd) | Directory path | ### Example ```bash cd ~/work && sibyl config context link work ``` --- ## config context unlink Remove the context pin from a directory. Any project link on the directory is kept. ### Synopsis ```bash sibyl config context unlink [options] ``` ### Options | Option | Short | Default | Description | | -------- | ----- | ------- | -------------- | | `--path` | `-p` | (cwd) | Directory path | ### Example ```bash sibyl config context unlink --path ~/work ``` --- ## config context update Update an existing context. ### Synopsis ```bash sibyl config context update <name> [options] ``` ### Arguments | Argument | Required | Description | | -------- | -------- | ---------------------- | | `name` | Yes | Context name to update | ### Options | Option | Short | Description | | ------------ | ----- | ----------------------------------------- | | `--server` | `-s` | New server URL | | `--org` | `-o` | New org slug (use 'auto' to clear) | | `--project` | `-p` | New default project (use 'none' to clear) | | `--insecure` | `-k` | Skip SSL verification | | `--secure` | | Re-enable SSL verification | | `--json` | `-j` | JSON output | ### Examples ```bash # Update server URL sibyl config context update prod --server https://new-sibyl.example.com # Change default project sibyl config context update staging --project proj_new_staging # Clear organization (use auto-detect) sibyl config context update local --org auto # Clear default project sibyl config context update dev --project none # Enable insecure mode sibyl config context update staging --insecure # Disable insecure mode sibyl config context update staging --secure ``` --- ## config context delete Delete a context. ### Synopsis ```bash sibyl config context delete <name> ``` ### Arguments | Argument | Required | Description | | -------- | -------- | ---------------------- | | `name` | Yes | Context name to delete | ### Example ```bash sibyl config context delete old-staging ``` Output: ``` Deleted context 'old-staging' ``` If you delete the active context: ``` Deleted context 'local' No active context. Use 'sibyl config context use <name>' to set one. ``` --- ## config context clear Clear the active context. Falls back to legacy `server.url` from config. ### Synopsis ```bash sibyl config context clear ``` ### Example ```bash sibyl config context clear ``` Output: ``` Cleared active context Using legacy server.url from config ``` --- ## Context Priority When resolving which context a command runs against, the CLI checks in this order: 1. `--context` / `-C` global flag (highest priority) 2. `SIBYL_CONTEXT` environment variable 3. Directory pin (`sibyl config context link`) 4. Active context (`sibyl config context use`) Every one of these takes a context **name**, never a project ID, and a name with no matching context stops the command. Nothing falls back to the active context, so a typo cannot send a write to the wrong server. ### Override with Flag ```bash # Run one command against another context sibyl --context staging task list sibyl -C staging task list ``` ### Override with Environment ```bash # Use another context for the shell session export SIBYL_CONTEXT=staging sibyl task list # Runs against staging ``` --- ## Common Workflows ### Solo / Local Only Most personal installs never need more than one context. `sibyl up` sets up a local context for you automatically; to create it by hand, this is the whole setup: ```bash sibyl config context create local --server http://localhost:3334 --use sibyl health ``` Everything else on this page is for people juggling multiple servers or orgs. ### Development Setup ```bash # Create contexts for different environments sibyl config context create local --server http://localhost:3334 --use sibyl config context create staging --server https://staging.sibyl.io --org myorg sibyl config context create prod --server https://sibyl.example.com --org myorg # Switch between environments sibyl config context use local sibyl config context use staging sibyl config context use prod ``` ### CI/CD Integration ```bash # In CI pipeline sibyl config context create ci \ --server "$SIBYL_URL" \ --org "$SIBYL_ORG" \ --use # Or select the context by name, without making it active export SIBYL_CONTEXT=ci sibyl task list --status todo ``` ### Multiple Organizations ```bash # Create context per org sibyl config context create work --server https://sibyl.company.com --org company sibyl config context create personal --server https://sibyl.io --org personal # Switch organizations sibyl config context use work sibyl config context use personal ``` ## Configuration File Contexts are stored in `~/.sibyl/config.toml`: ```toml [context] active = "local" [contexts.local] server_url = "http://localhost:3334" org_slug = "" default_project = "" insecure = false [contexts.prod] server_url = "https://sibyl.example.com" org_slug = "myorg" default_project = "proj_main" insecure = false [contexts.staging] server_url = "https://staging.internal:3334" org_slug = "myorg" default_project = "" insecure = true ``` ## Related Commands - `sibyl config context` - Manage named server, org, and project contexts - [`sibyl auth login`](./auth.md) - Log in and create a context in one step - [`sibyl project link`](./project.md) - Link directory to project - [`sibyl config`](./index.md) - Configuration management -
crawl.md 7.3 KB
# crawl Web crawling and documentation ingestion. `crawl` registers documentation sources, ingests them into the content store, and links the crawled chunks into the knowledge graph so they surface in [`sibyl context`](./context.md). ## Commands | Command | Description | | ----------------------------------------------- | ------------------------------------------ | | [`sibyl crawl list`](#crawl-list) | List crawl sources | | [`sibyl crawl add`](#crawl-add) | Add a new documentation source | | [`sibyl crawl ingest`](#crawl-ingest) | Start crawling a source | | [`sibyl crawl status`](#crawl-status) | Get crawl status for a source | | [`sibyl crawl show`](#crawl-show) | Show crawl source details | | [`sibyl crawl stats`](#crawl-stats) | Show crawling statistics | | [`sibyl crawl health`](#crawl-health) | Check crawl system health | | [`sibyl crawl delete`](#crawl-delete) | Delete a source and all its documents | | [`sibyl crawl link-status`](#crawl-link-status) | Show pending graph linking work per source | | [`sibyl crawl link-graph`](#crawl-link-graph) | Link crawled chunks into the graph | | [`sibyl crawl documents`](#crawl-documents) | Browse crawled documents | ## Workflow ``` add -> ingest -> link-graph -> search | | | source documents graph entities ``` Register a source with `add`, crawl it with `ingest`, then `link-graph` so the chunks become graph entities. `link-status` shows what still needs linking. --- ## crawl list List crawl sources. ```bash sibyl crawl list [options] ``` | Option | Short | Default | Description | | ---------- | ----- | ------- | ---------------- | | `--status` | `-s` | (all) | Filter by status | | `--limit` | `-n` | 20 | Max results | | `--json` | `-j` | false | JSON output | --- ## crawl add Add a new documentation source. ```bash sibyl crawl add <url> [options] ``` | Argument | Required | Description | | -------- | -------- | ------------------------ | | `url` | Yes | Documentation URL to add | | Option | Short | Default | Description | | ------------------------- | ----- | --------- | -------------------------------------------- | | `--name` | `-n` | (derived) | Source name | | `--type` | `-T` | `website` | Source type: `website`, `github`, `api_docs` | | `--depth` | `-d` | 2 | Crawl depth | | `--pattern` / `--include` | `-p` | (none) | URL patterns to include | | `--json` | `-j` | false | JSON output | ### Example ```bash sibyl crawl add https://docs.example.com \ --name "Example Docs" --type website --depth 3 \ --pattern "/guide/*" ``` --- ## crawl ingest Start crawling a documentation source. ```bash sibyl crawl ingest <source_id> [options] ``` | Argument | Required | Description | | ----------- | -------- | ------------------ | | `source_id` | Yes | Source ID to crawl | | Option | Short | Default | Description | | ------------- | ----- | ------- | ------------------------- | | `--max-pages` | `-p` | 50 | Maximum pages to crawl | | `--depth` | `-d` | 3 | Maximum link depth | | `--no-embed` | | false | Skip embedding generation | | `--json` | `-j` | false | JSON output | ### Examples ```bash sibyl crawl ingest abc123 --max-pages 100 sibyl crawl ingest abc123 --depth 2 --no-embed ``` --- ## crawl status Get the status of a crawl source using the current source-status contract. ```bash sibyl crawl status <source_id> [options] ``` | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | --- ## crawl show Show crawl source details. ```bash sibyl crawl show <source_id> [options] ``` | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | --- ## crawl stats Show crawling statistics across all sources. ```bash sibyl crawl stats [--json] ``` --- ## crawl health Check crawl system health. ```bash sibyl crawl health [--json] ``` --- ## crawl delete Delete a crawl source and all its documents. ```bash sibyl crawl delete <source_id> [options] ``` | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | --- ## crawl link-status Show pending graph linking work per source. Use this to see how many crawled chunks still need to be linked into the graph. ```bash sibyl crawl link-status [--json] ``` --- ## crawl link-graph Link crawled chunks into the graph. Pass a source ID, or `all` to process every source. ```bash sibyl crawl link-graph [source_id] [options] ``` | Argument | Required | Description | | ----------- | -------- | ----------------------------------- | | `source_id` | No | Source ID, or `all` for all sources | | Option | Short | Default | Description | | -------------- | ----- | ------- | ---------------------------------------------- | | `--batch` | `-b` | 50 | Batch size | | `--dry-run` | `-n` | false | Show what would be processed | | `--create-new` | | false | Create graph entities for unlinked extractions | | `--json` | `-j` | false | JSON output | ### Examples ```bash # Dry-run linking for one source sibyl crawl link-graph abc123 --dry-run # Link all sources, creating entities for new extractions sibyl crawl link-graph all --create-new ``` --- ## crawl documents Browse crawled documents. ### crawl documents list List crawled documents. ```bash sibyl crawl documents list [options] ``` | Option | Short | Default | Description | | ---------- | ----- | ------- | ------------------- | | `--source` | `-s` | (all) | Filter by source ID | | `--limit` | `-n` | 20 | Max results | | `--json` | `-j` | false | JSON output | ### crawl documents show Show full document content. Use the `document_id` from search result metadata. ```bash sibyl crawl documents show <document_id> [options] ``` | Argument | Required | Description | | ------------- | -------- | --------------------------------------- | | `document_id` | Yes | Document ID from search result metadata | | Option | Short | Description | | -------- | ----- | ------------------------- | | `--raw` | `-r` | Show raw markdown content | | `--json` | `-j` | JSON output | ### Example ```bash sibyl context "proto config" --json # note the document_id in result metadata sibyl crawl documents show 22d4cf79-8561-4be0-8067-da8673e3439d ``` ## Related Commands - [`sibyl context`](./context.md) - Load graph and document context for an agent goal - [`sibyl explore`](./explore.md) - Traverse linked document entities -
docker.md 4.7 KB
# docker Manage a self-hosted Sibyl Docker deployment. `docker` generates a pinned compose stack under `~/.sibyl/docker`, starts and stops it, tails its logs, and upgrades it to new image tags. It is the production-leaning path: explicit image tags, generated secrets, and optional worker and crawler services. For the simpler, batteries-included local instance, use [`sibyl local`](./local.md) (and its `sibyl up` / `sibyl down` aliases) instead. ## Commands | Command | Description | | ----------------------------------------- | ----------------------------------------------------- | | [`sibyl docker init`](#docker-init) | Generate pinned compose files under `~/.sibyl/docker` | | [`sibyl docker up`](#docker-up) | Start the Docker deployment | | [`sibyl docker logs`](#docker-logs) | Show Docker deployment logs | | [`sibyl docker down`](#docker-down) | Stop the Docker deployment | | [`sibyl docker upgrade`](#docker-upgrade) | Pull current images and recreate containers | --- ## docker init Generate pinned compose and env files under `~/.sibyl/docker` and create a matching context. ```bash sibyl docker init [options] ``` | Option | Short | Default | Description | | ------------------------------ | ----- | ------------- | --------------------------------- | | `--api-port` | | 3334 | Host API port | | `--web-port` | | 3337 | Host web port | | `--surreal-port` | | 8000 | Host SurrealDB port | | `--tag` | | (CLI version) | Sibyl image tag | | `--with-worker` | | false | Add Valkey and a worker service | | `--with-crawler` | | false | Use the crawler-enabled API image | | `--context` | | `docker` | Context name to create | | `--activate` / `--no-activate` | | on | Set the created context active | | `--force` | `-f` | false | Overwrite existing files | ### Examples ```bash # Generate the default stack and activate its context sibyl docker init # Pin a tag and add the worker + crawler services sibyl docker init --tag 1.4.0 --with-worker --with-crawler # Regenerate over an existing install sibyl docker init --force ``` --- ## docker up Start the deployment. Requires an initialized runtime and a working Docker install. ```bash sibyl docker up [options] ``` | Option | Default | Description | | -------- | ------- | --------------------------- | | `--pull` | false | Pull images before starting | --- ## docker logs Show deployment logs. Pass a service name to scope the output. ```bash sibyl docker logs [service] [options] ``` | Argument | Required | Description | | --------- | -------- | --------------------- | | `service` | No | Optional service name | | Option | Short | Default | Description | | -------------------------- | ----- | ------- | ----------------------- | | `--follow` / `--no-follow` | `-f` | on | Follow log output | | `--tail` | | 100 | Number of lines to show | --- ## docker down Stop the deployment. ```bash sibyl docker down [options] ``` | Option | Short | Default | Description | | ----------- | ----- | ------- | ------------------- | | `--volumes` | `-v` | false | Also remove volumes | --- ## docker upgrade Pull current images and recreate containers, optionally writing a new image tag first. ```bash sibyl docker upgrade [options] ``` | Option | Default | Description | | ------- | ------- | --------------------- | | `--tag` | (none) | Write a new image tag | ### Example ```bash sibyl docker upgrade --tag 1.4.0 ``` ## Notes - Ports bind to `127.0.0.1` only. The API is published on the API port, the web UI on the web port, and SurrealDB on the SurrealDB port. - `init` generates a SurrealDB password and JWT secret into a `0600` env file; keep that file safe. - The worker service requires Valkey, which `--with-worker` adds and wires up automatically. - Most subcommands refuse to run until you have run `docker init`. ## Related Commands - [`sibyl local`](./local.md) - Simpler local Docker instance with `sibyl up`/`down` - [`sibyl service`](./service.md) - Run a native host daemon instead of Docker - [`sibyl update`](./update.md) - Pull newer container images -
docs.md 5 KB
# docs Import and list document collections. `docs` brings local files, directories, and URLs into Sibyl as documents, and pastes ad-hoc text straight into a collection. Imported documents are chunked, embedded, and surfaced through [`sibyl context`](./context.md). This is distinct from [`sibyl crawl documents`](./crawl.md#crawl-documents), which browses pages captured by the web crawler. Use `docs` to push content in; use `crawl` to pull a site down. ## Commands | Command | Description | | --------------------------------- | ----------------------------------------- | | [`sibyl docs add`](#docs-add) | Import a document file, directory, or URL | | [`sibyl docs paste`](#docs-paste) | Import pasted text as a document | | [`sibyl docs list`](#docs-list) | List imported document collections | --- ## docs add Import a document file, a directory of documents, or a URL. Directory imports require `--recursive`. ```bash sibyl docs add <source> [options] ``` | Argument | Required | Description | | -------- | -------- | -------------------------------- | | `source` | Yes | Document file, directory, or URL | | Option | Short | Default | Description | | ------------------------- | ----- | ------- | --------------------------------------- | | `--recursive` | `-r` | false | Import a directory recursively | | `--collection` | `-c` | (none) | Collection label | | `--project` | `-p` | (auto) | Target project id or name | | `--batch-size` | | 100 | Import batch size | | `--drain` | | false | Wait for the background drain to finish | | `--poll-interval` | | 1.0 | Seconds between drain status checks | | `--timeout` | | (none) | Maximum seconds to wait when draining | | `--allow-private-network` | | false | Allow URL imports from private hosts | | `--json` | `-j` | false | JSON output for scripting | ### Examples ```bash # Import a single file into the linked project sibyl docs add ./runbook.md # Import a directory tree into a named collection sibyl docs add ./design-notes/ --recursive --collection "Design Notes" # Import a public URL and wait for it to finish sibyl docs add https://example.com/spec.html --drain ``` --- ## docs paste Import pasted text as a document. Reads from an argument, from `--file`, or from stdin with `-`. ```bash sibyl docs paste [text] [options] ``` | Argument | Required | Description | | -------- | -------- | ------------------------------- | | `text` | No | Document text, or `-` for stdin | | Option | Short | Default | Description | | ----------------- | ----- | ------- | --------------------------------------- | | `--file` | `-f` | (none) | Read document text from a file | | `--title` | `-t` | (none) | Document title | | `--collection` | `-c` | (none) | Collection label | | `--project` | `-p` | (auto) | Target project id or name | | `--batch-size` | | 100 | Import batch size | | `--drain` | | false | Wait for the background drain to finish | | `--poll-interval` | | 1.0 | Seconds between drain status checks | | `--timeout` | | (none) | Maximum seconds to wait when draining | | `--json` | `-j` | false | JSON output for scripting | ### Examples ```bash # Paste inline text with a title sibyl docs paste "Release checklist: tag, build, publish" --title "Release Checklist" # Pipe content from stdin cat NOTES.md | sibyl docs paste - --collection "Notes" # Import from a file sibyl docs paste --file ./meeting.txt --title "Standup 2026-06-23" ``` --- ## docs list List imported document collections with their document counts. ```bash sibyl docs list [options] ``` | Option | Short | Default | Description | | -------- | ----- | ------- | ------------------------- | | `--json` | `-j` | false | JSON output for scripting | ## Notes - File and directory sources must not contain symlinks; the path is fully resolved before upload. - A target project is required. `docs` uses the project linked to the current directory unless you pass `--project`. - Imports queue and drain in the background. Pass `--drain` to block until the import reaches a terminal state. - URL imports refuse private hosts by default; pass `--allow-private-network` to override. ## Related Commands - [`sibyl context`](./context.md) - Search documents alongside graph memory - [`sibyl crawl`](./crawl.md) - Crawl websites into the content store - [`sibyl ingest`](./ingest.md) - Import agent transcript JSONL into raw memory -
doctor.md 2.9 KB
# doctor Diagnose Sibyl config, daemon health, locks, write readiness, and agent setup. `doctor` runs a battery of checks against your active context and your local assistant integration, printing a pass/warn/fail table. It exits non-zero when any check fails, so it works as a preflight gate. ## Synopsis ```bash sibyl doctor [options] ``` ## Options | Option | Short | Default | Description | | ---------------------------------- | ----- | ------- | ----------------------------------------------------------------- | | `--json` | `-j` | false | Output as JSON | | `--timeout` | | 2.0 | Network timeout in seconds | | `--write-test` / `--no-write-test` | | on | Run the authenticated write probe | | `--skip-agent` | | false | Skip agent-setup checks (skill stub, hooks, CLAUDE.md) | | `--append` | | (none) | Append the recommended agent-setup block to a CLAUDE.md/AGENTS.md | ## Checks `doctor` reports on three areas: | Area | Checks | | ----------- | ---------------------------------------------------------------------------------- | | Config | Config file is readable, an active context resolves | | Runtime | API health, local port reachability, embedded SurrealDB lock, write probe | | Agent setup | Skill stub installed, SessionStart hook present, no legacy hook, CLAUDE.md content | For remote contexts the port and embedded-lock probes are skipped automatically. The write probe authenticates and performs a round-trip write, so it needs a logged-in context; disable it with `--no-write-test` when you only want read-side checks. ## Examples ```bash # Full health and setup report sibyl doctor # Skip the authenticated write probe sibyl doctor --no-write-test # Machine-readable output for CI sibyl doctor --json | jq '.ok' # Add the managed memory-loop block to your project CLAUDE.md sibyl doctor --append ./CLAUDE.md ``` ## Notes - When the agent-prompt check does not pass and `--append` is not given, `doctor` prints the recommended agent-setup block so you can paste it in by hand. - `--append` writes an idempotent, marker-delimited block, so re-running it updates the same block in place rather than duplicating it. - A non-zero exit means at least one check failed; warnings alone do not fail the run. ## Related Commands - [`sibyl init`](./init.md) - Create the context `doctor` checks - [`sibyl skill`](./skill.md) - Install the skill stub `doctor` looks for - [`sibyl local`](./local.md) - Set up Claude/Codex hooks with `local setup` -
entity.md 11.6 KB
# entity Generic entity CRUD operations. Use this for working with knowledge entities like patterns, episodes, templates, and other types. ## Commands - `sibyl entity list` - List entities by type - `sibyl entity show` - Show entity details - `sibyl entity create` - Create an entity - `sibyl entity delete` - Delete an entity - `sibyl entity related` - Show related entities - `sibyl entity history` - Show entity version history --- ## Entity Types Sibyl tracks 33 entity types. The full set: | Type | Description | | ------------------ | --------------------------------------------------- | | `pattern` | Code patterns, best practices | | `rule` | Rules and constraints | | `template` | Code templates | | `guide` | Team guidance, standards | | `tool` | Tools and utilities | | `language` | Programming languages | | `topic` | General topics | | `episode` | Knowledge episodes, learnings | | `knowledge_source` | External knowledge sources | | `config_file` | Configuration files | | `slash_command` | Slash commands | | `project` | Projects (use `sibyl project` instead) | | `epic` | Epics (use `sibyl epic` instead) | | `task` | Tasks (use `sibyl task` instead) | | `team` | Team definitions | | `error_pattern` | Error patterns and solutions | | `milestone` | Project milestones | | `source` | Web sources | | `document` | Crawled documents | | `procedure` | Procedures and processes | | `community` | Community groupings | | `note` | Standalone notes | | `domain` | Knowledge domains | | `artifact` | Produced outputs (synthesis, docs) | | `decision` | A choice made, with rationale | | `plan` | An intended sequence of work | | `idea` | An exploration or proposal | | `claim` | An assertion to be verified or cited | | `preference` | Like, dislike, habit, or stable personal constraint | | `person` | Named person or relationship anchor | | `place` | Location, venue, or destination | | `event` | Dated activity, milestone, or occurrence | | `session` | Session-level memory or summary | --- ## entity list List entities by type with optional filters. ### Synopsis ```bash sibyl entity list [options] ``` ### Options | Option | Short | Default | Description | | ------------ | ----- | --------- | ------------------- | | `--type` | `-T` | `pattern` | Entity type to list | | `--language` | `-l` | (all) | Filter by language | | `--category` | `-c` | (all) | Filter by category | | `--limit` | `-n` | 50 | Max results | | `--json` | `-j` | false | JSON output | | `--csv` | | false | CSV output | ### Examples ```bash # List patterns (default) sibyl entity list # List episodes sibyl entity list --type episode # List patterns for TypeScript sibyl entity list --type pattern --language typescript # List patterns in a category sibyl entity list --type pattern --category "error-handling" # JSON output sibyl entity list --type pattern --json ``` Output (table): ``` Patterns ID Name Description ─────────────────────────────────────────────────────────────────── ent_abc1... JWT Authentication Pattern Secure JWT token handling with... ent_def2... Error Boundary Pattern React error boundary for graceful... ent_ghi3... Repository Pattern Data access layer abstraction... Showing 3 pattern(s) ``` --- ## entity show Show detailed entity information. ### Synopsis ```bash sibyl entity show <entity_id> [options] ``` ### Arguments | Argument | Required | Description | | ----------- | -------- | ----------- | | `entity_id` | Yes | Entity ID | ### Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | ### Example ```bash sibyl entity show ent_abc123 ``` Output: ``` Pattern Details Name: JWT Authentication Pattern Type: pattern ID: ent_abc123def456789 Description: Secure JWT token handling with refresh token rotation Content: Use short-lived access tokens (15 min) with longer refresh tokens (7 days). Store refresh tokens in httpOnly cookies. Implement token rotation on refresh. Blacklist tokens on logout using Redis with TTL matching token expiry. Metadata: category: authentication languages: ["typescript", "javascript"] tags: ["jwt", "security", "auth"] ``` --- ## entity create Create a new entity. ### Synopsis ```bash sibyl entity create --type <type> --name <name> [options] ``` ### Required Options | Option | Short | Description | | -------- | ----- | ---------------------- | | `--type` | `-T` | Entity type (required) | | `--name` | `-n` | Entity name (required) | ### Options | Option | Short | Description | | ------------- | ----- | ------------------------- | | `--content` | `-c` | Entity content | | `--category` | | Category | | `--languages` | `-l` | Comma-separated languages | | `--tags` | | Comma-separated tags | | `--json` | `-j` | JSON output | ### Examples ```bash # Create a pattern sibyl entity create \ --type pattern \ --name "Repository Pattern" \ --content "Abstract data access behind interfaces. Each aggregate root gets its own repository." \ --category "architecture" \ --languages "typescript,java" \ --tags "ddd,clean-architecture" # Create an episode sibyl entity create \ --type episode \ --name "Redis Connection Pooling Fix" \ --content "Connection timeout was caused by exhausted pool. Increased max connections to 20." \ --category "debugging" # Create an error pattern sibyl entity create \ --type error_pattern \ --name "ECONNREFUSED on localhost" \ --content "Service not running or wrong port. Check docker-compose and port mappings." \ --tags "docker,networking,debugging" ``` Output: ``` Entity created: ent_xyz789abc123 ``` --- ## entity delete Delete an entity. ### Synopsis ```bash sibyl entity delete <entity_id> [options] ``` ### Arguments | Argument | Required | Description | | ----------- | -------- | ------------------- | | `entity_id` | Yes | Entity ID to delete | ### Options | Option | Short | Description | | -------- | ----- | ----------------- | | `--yes` | `-y` | Skip confirmation | | `--json` | `-j` | JSON output | ### Example ```bash sibyl entity delete ent_abc123 --yes ``` Output: ``` Entity deleted: ent_abc1... ``` --- ## entity related Show entities related to a given entity (1-hop connections). ### Synopsis ```bash sibyl entity related <entity_id> [options] ``` ### Arguments | Argument | Required | Description | | ----------- | -------- | ----------- | | `entity_id` | Yes | Entity ID | ### Options | Option | Short | Default | Description | | --------- | ----- | ------- | ----------- | | `--limit` | `-n` | 20 | Max results | | `--json` | `-j` | false | JSON output | ### Example ```bash sibyl entity related ent_abc123 ``` Output: ``` Related Entities ID Name Type Relationship ──────────────────────────────────────────────────────────────────── ent_def4... OAuth2 Integration pattern RELATES_TO ent_ghi5... Session Management pattern RELATES_TO task_jkl... Implement auth flow task USED_IN proj_mno... Backend API project BELONGS_TO Found 4 related entity(ies) ``` --- ## entity history Show version history for an entity, including changes over time. ### Synopsis ```bash sibyl entity history <entity_id> [options] ``` ### Arguments | Argument | Required | Description | | ----------- | -------- | ----------- | | `entity_id` | Yes | Entity ID | ### Options | Option | Short | Default | Description | | ------------------- | ----- | --------- | --------------------------------------------------- | | `--as-of` | `-d` | (now) | Point-in-time (ISO date, e.g. `2025-03-15`) | | `--mode` | `-m` | `history` | Display mode: `history`, `timeline`, or `conflicts` | | `--include-expired` | `-e` | false | Include expired edges | | `--limit` | `-n` | 50 | Max results | | `--json` | `-j` | false | JSON output | The history modes operate on edges over time: - `history` shows edges as they existed at a point in time (use `--as-of`). - `timeline` shows every version of edges over time, surfacing evolution. - `conflicts` finds invalidated or superseded facts. ### Examples ```bash # Show full version history sibyl entity history ent_abc123 # Show state at a specific point in time sibyl entity history ent_abc123 --as-of "2024-06-01T00:00:00Z" # Show timeline view sibyl entity history ent_abc123 --mode timeline # Show conflicting versions sibyl entity history ent_abc123 --mode conflicts # Include expired versions sibyl entity history ent_abc123 --include-expired ``` --- ## Common Workflows ### Knowledge Management ```bash # Search for existing patterns sibyl context "review existing error-handling patterns" --intent review # If not found, create one sibyl entity create \ --type pattern \ --name "Global Error Handler Pattern" \ --content "Centralize error handling with middleware. Log errors, sanitize for clients." # Find related knowledge sibyl entity related ent_abc123 ``` ### Documenting Solutions ```bash # After solving a bug, document it sibyl entity create \ --type error_pattern \ --name "TypeORM Connection Lost" \ --content "Connection lost after idle timeout. Fix: Enable keepalive in connection options." \ --tags "typeorm,postgresql,connection" ``` ### Browsing Knowledge ```bash # List all error patterns sibyl entity list --type error_pattern # List patterns by language sibyl entity list --type pattern --language rust # Get details on a specific pattern sibyl entity show ent_abc123 ``` ## Related Commands - [`sibyl remember`](./remember.md) - Quick knowledge capture (simpler interface) - [`sibyl remember`](./remember.md) - Typed memory-loop writes - [`sibyl context`](./context.md) - Semantic search - [`sibyl explore related`](./explore.md) - Graph exploration -
epic.md 11.7 KB
# epic Epic lifecycle management. Epics are feature groups that organize related tasks within a project. ::: warning Deprecated An epic is just a task with subtasks. Prefer `sibyl task` and group children with `sibyl task create --epic <id>`. These commands keep working as sugar over the task tree. ::: ## Epic States ``` planning -> in_progress -> completed | v blocked -> in_progress any -> archived ``` ## Commands - `sibyl epic list` - List epics - `sibyl epic show` - Show epic details - `sibyl epic create` - Create an epic - `sibyl epic start` - Start an epic - `sibyl epic complete` - Complete an epic - `sibyl epic archive` - Archive an epic - `sibyl epic update` - Update epic fields - `sibyl epic tasks` - List tasks in an epic - `sibyl epic roadmap` - Generate markdown roadmap document --- ## epic list List epics with optional filters. ### Synopsis ```bash sibyl epic list [options] ``` ### Options | Option | Short | Default | Description | | ----------- | ----- | ------- | ------------------------------------------------- | | `--project` | `-p` | (auto) | Project ID | | `--status` | `-s` | (all) | Filter: planning, in_progress, blocked, completed | | `--limit` | `-n` | 50 | Max results | | `--json` | `-j` | false | JSON output | | `--all` | `-A` | false | Ignore context, list from all projects | ### Examples ```bash # List epics in current project sibyl epic list # List all in_progress epics sibyl epic list --status in_progress # List epics across all projects sibyl epic list --all ``` Output: ``` Epics ID Title Status Priority Progress ─────────────────────────────────────────────────────────────────────────── epic_abc123... Authentication System in_progress high 5/12 epic_def456... API v2 Migration planning medium 0/8 epic_ghi789... Performance Optimization in_progress high 3/7 Showing 3 epic(s) ``` --- ## epic show Show detailed epic information including progress. ### Synopsis ```bash sibyl epic show <epic_id> [options] ``` ### Arguments | Argument | Required | Description | | --------- | -------- | ------------ | | `epic_id` | Yes | Full epic ID | ### Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | ### Example ```bash sibyl epic show <epic_id> ``` Output: ``` Epic epic_abc123de Title: Authentication System Status: in_progress Priority: high Progress: 5/12 tasks (41.7%) Project: proj_xyz7... Leads: nova, bliss Description: Complete authentication overhaul including OAuth2, MFA, and session management. Tags: security, auth, oauth ``` --- ## epic create Create a new epic in a project. ### Synopsis ```bash sibyl epic create --title <title> [options] ``` ### Required Options | Option | Description | | ---------------- | --------------------- | | `--title` / `-n` | Epic title (required) | ### Options | Option | Short | Default | Description | | --------------- | ----- | -------- | ---------------------------------------------- | | `--project` | `-p` | (auto) | Project ID (auto-resolves from linked path) | | `--description` | `-d` | (none) | Epic description | | `--priority` | | `medium` | Priority: critical, high, medium, low, someday | | `--assignee` | `-a` | (none) | Epic lead/owner | | `--tags` | | (none) | Comma-separated tags | | `--sync` | | false | Wait for creation | | `--json` | `-j` | false | JSON output | ### Examples ```bash # Basic epic sibyl epic create --title "Authentication System" # Full example sibyl epic create \ --title "Authentication System" \ --description "OAuth2, MFA, session management overhaul" \ --priority high \ --assignee "nova" \ --tags "security,auth,oauth" ``` Output: ``` Epic created: epic_abc123def456 Lead: nova ``` --- ## epic start Start working on an epic. Moves status to `in_progress`. ### Synopsis ```bash sibyl epic start <epic_id> [options] ``` ### Options | Option | Short | Description | | ------------ | ----- | ----------- | | `--assignee` | `-a` | Epic lead | | `--json` | `-j` | JSON output | ### Example ```bash sibyl epic start epic_abc123 ``` Output: ``` Epic started: epic_abc123... ``` --- ## epic complete Complete an epic. ### Synopsis ```bash sibyl epic complete <epic_id> [options] ``` ### Options | Option | Short | Description | | ------------- | ----- | --------------------------- | | `--learnings` | `-l` | Key learnings from the epic | | `--json` | `-j` | JSON output | ### Example ```bash sibyl epic complete epic_abc123 \ --learnings "OAuth2 integration was smoother than expected. Key insight: use passport.js for strategy abstraction." ``` Output: ``` Epic completed: epic_abc123... Learnings captured ``` --- ## epic archive Archive an epic (terminal state). ### Synopsis ```bash sibyl epic archive <epic_id> [options] ``` ### Options | Option | Short | Description | | ---------- | ----- | ----------------- | | `--reason` | `-r` | Archive reason | | `--yes` | `-y` | Skip confirmation | | `--json` | `-j` | JSON output | ### Example ```bash sibyl epic archive epic_abc123 --reason "Superseded by epic_xyz" --yes ``` Output: ``` Epic archived: epic_abc123def456... ``` --- ## epic update Update epic fields directly. ### Synopsis ```bash sibyl epic update <epic_id> [options] ``` ### Options | Option | Short | Description | | ------------ | ----- | ------------------------------------------------- | | `--status` | `-s` | Status: planning, in_progress, blocked, completed | | `--priority` | `-p` | Priority: critical, high, medium, low, someday | | `--title` | | Epic title | | `--assignee` | `-a` | Epic lead | | `--tags` | | Comma-separated tags | | `--json` | `-j` | JSON output | ### Examples ```bash # Change priority sibyl epic update epic_abc123 --priority critical # Update multiple fields sibyl epic update epic_abc123 \ --status in_progress \ --assignee "bliss" \ --tags "security,urgent" ``` Output: ``` Epic updated: epic_abc123def456... Fields: status, assignees, tags ``` --- ## epic tasks List tasks belonging to an epic. ### Synopsis ```bash sibyl epic tasks <epic_id> [options] ``` ### Options | Option | Short | Default | Description | | ---------- | ----- | ------- | --------------------- | | `--status` | `-s` | (all) | Filter by task status | | `--limit` | `-n` | 50 | Max results | | `--json` | `-j` | false | JSON output | ### Examples ```bash # All tasks in epic sibyl epic tasks epic_abc123 # Only todo tasks sibyl epic tasks epic_abc123 --status todo # JSON for scripting sibyl epic tasks epic_abc123 --json ``` Output: ``` Tasks ID Title Status Priority Assignees ─────────────────────────────────────────────────────────────────────────── task_abc12... Setup OAuth2 provider done high nova task_def45... Implement MFA doing high bliss task_ghi78... Add session management todo medium - task_jkl01... Write auth tests todo medium nova Showing 4 task(s) for epic ``` --- ## Common Workflows ### Epic Planning ```bash # Create epic sibyl epic create \ --title "User Dashboard" \ --description "New user dashboard with analytics and settings" \ --priority high # Create tasks under epic sibyl task create --title "Design dashboard layout" --epic epic_abc123 sibyl task create --title "Implement analytics widgets" --epic epic_abc123 sibyl task create --title "Add user settings panel" --epic epic_abc123 sibyl task create --title "Write dashboard tests" --epic epic_abc123 # Check progress sibyl epic show epic_abc123 ``` ### Epic Execution ```bash # Start the epic sibyl epic start epic_abc123 --assignee "nova" # Check task status sibyl epic tasks epic_abc123 --status todo # Start first task sibyl task start task_design --assignee "nova" # Monitor progress sibyl epic show epic_abc123 ``` ### Completing Epics ```bash # Check remaining tasks sibyl epic tasks epic_abc123 --status todo,doing,blocked # If all done, complete epic sibyl epic complete epic_abc123 \ --learnings "Dashboard component architecture worked well. Consider extracting widget framework for reuse." ``` ### Moving Tasks to Epic ```bash # Find orphan tasks sibyl task list --no-epic # Assign to epic sibyl task update task_xyz --epic epic_abc123 ``` ## epic roadmap Generate a markdown roadmap document from epics and tasks. ### Synopsis ```bash sibyl epic roadmap [options] ``` ### Options | Option | Short | Default | Description | | ---------------- | ----- | ------- | ---------------------------------------------- | | `--project` | `-p` | (auto) | Project ID | | `--status` | `-s` | (all) | Filter epics: planning, in_progress, completed | | `--include-done` | | false | Include completed tasks in output | | `--output` | `-o` | stdout | Output file path | ### Output Includes - **Overview table**: Epic counts by status - **Each epic**: Title, priority badge, status, description, progress bar - **Tasks by status**: To Do, In Progress, Blocked, Review, Done - **Priority markers**: 🔴 critical, 🟠 high on task names - **Key Learnings**: Aggregated learnings from completed tasks ### Examples ```bash # Generate roadmap to stdout sibyl epic roadmap # Save to file sibyl epic roadmap -o roadmap.md # Include completed tasks sibyl epic roadmap --include-done # Only in-progress epics sibyl epic roadmap --status in_progress # Specific project sibyl epic roadmap --project proj_abc123 ``` ### Example Output ```markdown # Sibyl Roadmap _Generated: 2026-01-04 11:08_ ## Overview | Status | Count | | ----------- | ------ | | Planning | 11 | | In Progress | 0 | | Completed | 2 | | **Total** | **13** | ## Epics ### 📋 Server Setup Wizard **ID:** `epic_b3145...` | **Priority:** 🔴 critical | **Status:** planning > Web-based first-run wizard that guides users through setup... **Progress:** `[████████████████░░░░]` 9/11 (82%) #### 📝 To Do - [ ] 🔴Backend: First-user-is-admin logic (`task_daab...`) **Done:** 8 task(s) _(use --include-done to show)_ --- ## Key Learnings - **Replace inline SVGs** (Server Setup Wizard) > Iconoir icons are already exported from @/components/ui/icons.tsx... ``` --- ## Related Commands - [`sibyl task create`](./task-create.md) - Create task (with `--epic`) - [`sibyl task list`](./task-list.md) - List tasks (with `--epic` filter) - [`sibyl project show`](./project.md) - Project overview -
explore.md 6.4 KB
# explore Graph traversal and exploration commands. Navigate the knowledge graph to discover relationships and dependencies. ## Commands - `sibyl explore related` - Find directly connected entities (1-hop) - `sibyl explore traverse` - Multi-hop graph traversal - `sibyl explore dependencies` - Task dependency graph - `sibyl explore path` - Find shortest path between entities --- ## explore related Find entities directly connected to a given entity. ### Synopsis ```bash sibyl explore related <entity_id> [options] ``` ### Arguments | Argument | Required | Description | | ----------- | -------- | ------------------ | | `entity_id` | Yes | Starting entity ID | ### Options | Option | Short | Default | Description | | --------- | ----- | ------- | ---------------------------------------------- | | `--rel` | `-r` | (all) | Relationship types to follow (comma-separated) | | `--limit` | `-n` | 20 | Maximum results | | `--json` | `-j` | false | JSON output | ### Examples ```bash # Find all related entities sibyl explore related task_abc123 # Filter by relationship type sibyl explore related task_abc123 --rel "DEPENDS_ON,BLOCKS" # JSON output sibyl explore related task_abc123 --json ``` Output (table): ``` Related Entities ID Name Type Relationship ──────────────────────────────────────────────────────────── ent_xyz7... Update authentication task DEPENDS_ON ent_def4... Auth service refactor task BLOCKS proj_abc... Backend API project BELONGS_TO ``` --- ## explore traverse Multi-hop graph traversal from an entity. Discovers entities up to N hops away. ### Synopsis ```bash sibyl explore traverse <entity_id> [options] ``` ### Arguments | Argument | Required | Description | | ----------- | -------- | ------------------ | | `entity_id` | Yes | Starting entity ID | ### Options | Option | Short | Default | Description | | --------- | ----- | ------- | --------------------- | | `--depth` | `-d` | 2 | Traversal depth (1-3) | | `--limit` | `-n` | 50 | Maximum results | | `--json` | `-j` | false | JSON output | ### Examples ```bash # Default 2-hop traversal sibyl explore traverse task_abc123 # Shallow traversal (direct connections only) sibyl explore traverse task_abc123 --depth 1 # Deep traversal sibyl explore traverse task_abc123 --depth 3 --limit 100 ``` Output (tree): ``` Traversal from task_abc1... Hop 1 (5 entities) task Fix authentication bug task Update user model project Backend API pattern JWT handling epic Security improvements Hop 2 (12 entities) task Add logging task Database migration ... and 10 more Total: 17 entities across 2 hop(s) ``` ::: warning Depth Limit Maximum depth is 3 to prevent performance issues. For deep graph exploration, use multiple targeted traversals. ::: --- ## explore dependencies Show task dependency graph with topological ordering. Essential for understanding task execution order. ### Synopsis ```bash sibyl explore dependencies [entity_id] [options] ``` ### Arguments | Argument | Required | Description | | ----------- | -------- | --------------------------------------- | | `entity_id` | No | Task or Project ID (or use `--project`) | ### Options | Option | Short | Default | Description | | ----------- | ----- | ------- | ------------------------------- | | `--project` | `-p` | (none) | Project ID for all dependencies | | `--json` | `-j` | false | JSON output | ### Examples ```bash # Dependencies for a specific task sibyl explore dependencies task_abc123 # All dependencies in a project sibyl explore dependencies --project proj_xyz789 # JSON output for CI/CD sibyl explore dependencies --project proj_xyz --json ``` Output (table): ``` Dependency Order (execute top to bottom): 1. task_abc1 Setup database schema todo (blocks: 3) 2. task_def2 Create user model todo (deps: 1, blocks: 2) 3. task_ghi3 Add authentication doing (deps: 1, blocks: 1) 4. task_jkl4 Write API tests todo (deps: 2) 5. task_mno5 Deploy to staging todo (deps: 3) Total: 5 task(s) in dependency order ``` ### Circular Dependencies The command detects circular dependencies: ``` Warning: Circular dependencies detected! Dependency Order (execute top to bottom): ... ``` JSON output includes a `has_cycles` flag: ```json { "entities": [...], "has_cycles": true } ``` --- ## explore path Find the shortest path between two entities in the graph. ### Synopsis ```bash sibyl explore path <from_id> <to_id> [options] ``` ### Arguments | Argument | Required | Description | | --------- | -------- | ------------------ | | `from_id` | Yes | Starting entity ID | | `to_id` | Yes | Target entity ID | ### Options | Option | Short | Default | Description | | --------- | ----- | ------- | ------------------- | | `--depth` | `-d` | 5 | Maximum path length | | `--json` | `-j` | false | JSON output | ### Examples ```bash # Find path between two entities sibyl explore path task_abc123 task_xyz789 # Limit search depth sibyl explore path ent_start ent_end --depth 3 ``` Output: ``` Path Found (length: 3) task_abc1... | hop 1 | hop 2 | hop 3 | task_xyz7... ``` ### No Path Found ``` No path found between task_abc1 and task_xyz7 (max depth: 5) ``` --- ## Common Patterns ### Discovering Impact Find what depends on a task before making changes: ```bash sibyl explore related task_abc --rel "BLOCKED_BY" ``` ### Understanding Context Traverse from a task to understand its context: ```bash sibyl explore traverse task_abc --depth 2 ``` ### Sprint Planning Get dependency-ordered tasks for a project: ```bash sibyl explore dependencies --project proj_sprint01 --json | jq '.entities' ``` ### Finding Connections Check if two entities are connected: ```bash sibyl explore path ent_a ent_b --depth 4 ``` ## Related Commands - [`sibyl entity related`](./entity.md) - Entity-specific related lookup - [`sibyl task list`](./task-list.md) - Filter tasks - [`sibyl context`](./context.md) - Semantic search -
export.md 6.9 KB
# Export Memory to Files Materialize a project's memory into `.sibyl/memory/`, a directory of Markdown files that any filesystem-native agent can read and grep without talking to a Sibyl server. The graph stays the source of truth. This is a curated projection of it: structured substrate, flat-file surface. ## Usage ```bash sibyl export memory sibyl export memory --project sibyl sibyl export memory --output docs/memory --notes 100 ``` With no `--project`, the command uses the project linked to the current directory (see [`sibyl project link`](./project.md)). ## Why Files Every major coding agent in 2026 reads Markdown from the repository it is working in. A repo-local `.sibyl/memory/` is legible to all of them with zero integration work, costs nothing per read, and keeps working when the server does not. Recording usage still goes over the API (`sibyl cite <id>`), so the citation signal stays honest. ## Layout ``` .sibyl/memory/ ├── README.md # what this is, how to read it, how to cite it ├── index.md # every materialized memory, grouped by type, with ids and paths ├── handbook.md # distilled project handbook, composed from cited memories ├── recent.md # recency-ordered digest with previews ├── tasks.md # open work with task ids ├── notes/ # one file per memory, full text │ └── <type>-<title-slug>.md └── manifest.json # per-file SHA-256 plus a digest over the whole projection ``` Three tiers, deliberately: `README.md` and `handbook.md` orient, `index.md` / `recent.md` / `tasks.md` are the greppable middle, and `notes/` holds the detail an agent opens once grep points at it. `handbook.md` is composed during the export from the project's own memories, one synthesis run over the graph. Every line in it cites the memory it came from, and a heading with nothing behind it says so rather than being padded. Pass `--no-handbook` to skip the composition; the file is then simply absent, so nothing downstream has to special-case a placeholder. It is built per export rather than cached. The pipeline is deterministic search and rendering with no model call, so recomputing is cheap and the handbook cannot drift out of step with the graph it describes. ## File Format Every Markdown file opens with YAML frontmatter carrying a `type`, which makes the projection OKF v0.1-compatible: Markdown with YAML frontmatter in a git-shippable directory. Sibyl-specific keys are namespaced under `sibyl_`. ```markdown --- type: "Sibyl Pattern" title: "Pool Surreal connections per org" description: "Each org gets a dedicated connection-pooled client scoped to its namespace…" timestamp: "2026-07-22T09:30:00Z" okf_version: "0.1" sibyl_schema_version: "sibyl-memory-files-v1" sibyl_kind: "memory_note" sibyl_id: "pattern_a1b2c3d4" sibyl_entity_type: "pattern" sibyl_project_id: "project_05eb5c8c782a" --- # Pool Surreal connections per org ...full memory body... ## Provenance - Sibyl id: `pattern_a1b2c3d4` - Entity type: `pattern` - Cite with: `sibyl cite pattern_a1b2c3d4` ``` This differs from `sibyld export okf`, which embeds a lossless JSON payload in frontmatter so an archive can round-trip back into a graph. That format is for backup and portability. This one is for reading, so it carries only the fields a reader needs. ## Determinism Re-running against an unchanged graph rewrites **byte-identical files**. The directory is meant to live in git, and a projection that churned on every run would bury real changes in noise. Three rules make that hold: - **No wall-clock values.** Nothing samples `datetime.now()`. Timestamps in the output come from the data. `manifest.json` carries a content digest instead of an export time. - **Whitelisted fields.** Retrieval counters, last-recalled stamps, embedding metadata, and internal record handles all change when memory is merely _read_. None of them reach the files. - **Total ordering.** Records sort by id for file placement and by recency (id as tiebreak) for reading order, so the order the server returned them in cannot leak into the bytes. Verify a materialized directory at any time: ```bash sibyl export memory --output /tmp/check --json | jq -r .content_digest jq -r .content_digest .sibyl/memory/manifest.json ``` ## Options | Option | Short | Default | Description | | --------------- | ----- | ---------------- | ------------------------------------------------------ | | `--project` | `-p` | linked project | Project id or name to materialize | | `--output` | `-o` | `.sibyl/memory` | Directory to write into | | `--notes` | - | `60` | Maximum memories to include | | `--tasks` | - | `25` | Maximum open tasks to include | | `--task-status` | - | `doing,blocked` | Comma-separated task statuses to materialize | | `--type` | `-T` | ten memory types | Memory entity type to include (repeatable) | | `--hydrate` | - | true | Refetch each entity for its full body | | `--writable` | - | false | Leave files writable instead of read-only | | `--force` | - | false | Write into a populated directory that is not an export | | `--json` | `-j` | false | Print the export receipt as JSON | The note budget is spread across the requested types in round-robin rather than spent on whichever type the backend happens to order first, so a 40-item export covers decisions, patterns, procedures, claims, and the rest instead of forty decisions. `--hydrate` costs one extra request per memory. Turning it off is faster and yields 500-character previews, which defeats the point for anything but a smoke test. ## Reading the Result ```bash # what does this project know about connection pooling? rg -i 'connection pool' .sibyl/memory/notes # every decision, by file rg -l 'type: "Sibyl Decision"' .sibyl/memory/notes # what is open right now? cat .sibyl/memory/tasks.md ``` Files are written read-only. Edit the graph, not the directory: the next export overwrites everything Sibyl manages. `manifest.json` is the only authority on what Sibyl owns, which makes the write path safe in two ways. A file this exporter never wrote is never deleted, wherever it sits, so your own notes under `notes/` survive a re-export. And a populated directory holding no `manifest.json` is refused rather than overwritten, so `--output .` in a repo root cannot eat that repo's `README.md`. Pass `--force` when you genuinely mean to write into one. ## Related Commands - [`sibyl context`](./context.md) - Live, goal-scoped context pack from the server - [`sibyl session`](./session.md) - Wake-up bundle for the current session - [`sibyl project`](./project.md) - Link a directory to a project -
index.md 14.1 KB
# 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`](./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 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 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: 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 `--all` or `-a` - Use the global flag `--context` / `-C` to override -
ingest.md 4.5 KB
# ingest Import local source archives into raw memory. `ingest` reads exported agent transcripts as JSONL and streams each turn into Sibyl's raw memory store, where [`sibyl reflect`](./reflect.md) can later promote it into durable graph memory. This is the transcript path. For files, directories, and URLs of arbitrary documents, use [`sibyl docs`](./docs.md); for crawling websites, use [`sibyl crawl`](./crawl.md). ## Commands | Command | Description | | ------------------------------------------------- | ----------------------------------- | | [`sibyl ingest claude-code`](#ingest-claude-code) | Import Claude Code transcript JSONL | | [`sibyl ingest codex`](#ingest-codex) | Import Codex transcript JSONL | Both subcommands share the same options and the same import pipeline; only the source adapter differs. --- ## ingest claude-code Import a Claude Code transcript JSONL file or a directory of them. ```bash sibyl ingest claude-code <source> [options] ``` | Argument | Required | Description | | -------- | -------- | ----------------------------------- | | `source` | Yes | Claude Code JSONL file or directory | | Option | Default | Description | | ------------------- | --------- | ----------------------------------------------- | | `--scope` | `private` | Target memory scope | | `--scope-key` | (none) | Target scope key for project/team/shared scopes | | `--source-identity` | (none) | Stable identity for moved transcript exports | | `--batch-size` | 100 | Import batch size | | `--drain` | false | Wait for the background drain to finish | | `--poll-interval` | 1.0 | Seconds between drain status checks | | `--timeout` | (none) | Maximum seconds to wait when draining | | `--json` / `-j` | false | JSON output for scripting | ### Examples ```bash # Import a single session export sibyl ingest claude-code ~/.claude/projects/sibyl/session.jsonl # Import a directory and wait for it to finish sibyl ingest claude-code ~/.claude/projects/sibyl/ --drain # Import into a shared project scope as JSON sibyl ingest claude-code session.jsonl --scope project --scope-key sibyl --json ``` --- ## ingest codex Import a Codex transcript JSONL file or a directory of them. Identical to `claude-code` apart from the source format. ```bash sibyl ingest codex <source> [options] ``` | Argument | Required | Description | | -------- | -------- | ----------------------------- | | `source` | Yes | Codex JSONL file or directory | | Option | Default | Description | | ------------------- | --------- | ----------------------------------------------- | | `--scope` | `private` | Target memory scope | | `--scope-key` | (none) | Target scope key for project/team/shared scopes | | `--source-identity` | (none) | Stable identity for moved transcript exports | | `--batch-size` | 100 | Import batch size | | `--drain` | false | Wait for the background drain to finish | | `--poll-interval` | 1.0 | Seconds between drain status checks | | `--timeout` | (none) | Maximum seconds to wait when draining | | `--json` / `-j` | false | JSON output for scripting | ### Examples ```bash sibyl ingest codex ~/.codex/sessions/today.jsonl sibyl ingest codex ~/.codex/sessions/ --drain --timeout 120 ``` ## Notes - The source must be a real file or directory, not a symlink, and the path is resolved before upload. - Imports queue by default and drain in the background. Pass `--drain` to block until the import reaches a terminal state (`completed`, `failed`, or `canceled`). - Each imported turn lands as a raw memory. Use `--source-identity` to keep dedupe stable when you move or rename the same export between runs. ## Related Commands - [`sibyl reflect`](./reflect.md) - Promote raw memories into graph memory - [`sibyl context`](./context.md) - Recall raw memories with `--raw` - [`sibyl docs`](./docs.md) - Import files, directories, or URLs as documents - [`sibyl crawl`](./crawl.md) - Crawl and ingest documentation sites -
init.md 2.5 KB
# init Create an explicit local or remote context for first-run setup. `init` writes a named context into your Sibyl config and makes it active, so subsequent commands know which server to talk to. Run it once when you first set Sibyl up, then verify with [`sibyl doctor`](./doctor.md). A context is either local (a Sibyl daemon on this machine) or remote (a hosted Sibyl server). Pass `--local` for the former, `--remote <url>` for the latter; the two cannot be combined. ## Synopsis ```bash sibyl init [options] ``` ## Options | Option | Short | Default | Description | | ------------ | ----- | ---------------- | ----------------------------------------- | | `--remote` | | (none) | Remote Sibyl server URL for CLI-only mode | | `--local` | | false | Create a localhost context | | `--name` | `-n` | `local`/`remote` | Context name | | `--org` | `-o` | (auto) | Organization slug | | `--project` | `-p` | (none) | Default project ID | | `--insecure` | `-k` | false | Skip SSL verification for this context | | `--force` | `-f` | false | Update an existing context | | `--json` | `-j` | false | Output as JSON | When `--remote` is omitted the server URL defaults to `http://localhost:3334`. The context name defaults to `remote` when `--remote` is set and `local` otherwise. ## Examples ```bash # Local first-run setup sibyl init --local # Point the CLI at a hosted server sibyl init --remote https://your-sibyl-host --org acme # Update an existing context in place sibyl init --remote https://your-sibyl-host --force # Name a context and set a default project sibyl init --local --name dev --project sibyl ``` ## Notes - `init` refuses to overwrite an existing context unless you pass `--force`. - After a local init, the suggested next step is `sibyl serve` then `sibyl doctor`. After a remote init, it is `sibyl auth login` then `sibyl doctor`. - `--insecure` disables SSL verification for the context and is intended for self-signed dev servers only. ## Related Commands - [`sibyl doctor`](./doctor.md) - Verify config and daemon health after init - [`sibyl config context`](./context.md) - List, switch, and edit contexts - [`sibyl auth`](./auth.md) - Log in to a remote context - [`sibyl local`](./local.md) - Run a Docker-based local instance instead -
local.md 4.4 KB
# local Manage a local Sibyl instance (Docker-based). `local` runs the full Sibyl stack (API, worker, web UI, and SurrealDB) in Docker with batteries included: first run prompts for API keys, generates secrets, writes a compose file under `~/.sibyl/local`, and opens the web UI. The top-level [`sibyl up`](#local-start) and [`sibyl down`](#local-stop) commands are aliases of `local start` and `local stop`. For a pinned, production-leaning stack with explicit image tags, use [`sibyl docker`](./docker.md) instead. ## Commands | Command | Description | | ------------------------------------- | --------------------------------------------- | | [`sibyl local start`](#local-start) | Start the local instance (alias: `sibyl up`) | | [`sibyl local stop`](#local-stop) | Stop the local instance (alias: `sibyl down`) | | [`sibyl local status`](#local-status) | Show status of local services | | [`sibyl local logs`](#local-logs) | Show logs from local services | | [`sibyl local reset`](#local-reset) | Reset the instance (removes all data) | | [`sibyl local setup`](#local-setup) | Set up Claude/Codex integration | --- ## local start Start the local instance. On first run, prompts for API keys and generates secrets; later runs reuse saved configuration. Also available as `sibyl up`. ```bash sibyl local start [options] sibyl up [options] ``` | Option | Default | Description | | -------------- | ------- | ------------------------------------- | | `--no-browser` | false | Don't open the browser after starting | | `--pull` | false | Pull latest images before starting | ### Examples ```bash # Start and open the web UI sibyl up # Start headless and pull fresh images sibyl up --no-browser --pull ``` --- ## local stop Stop the local instance. Also available as `sibyl down`. ```bash sibyl local stop [options] sibyl down [options] ``` | Option | Default | Description | | ----------- | ------- | -------------------------------------- | | `--destroy` | false | Also remove volumes (deletes all data) | --- ## local status Show the status of local Sibyl services. ```bash sibyl local status ``` --- ## local logs Show logs from local Sibyl services. Pass a service name to scope the output. ```bash sibyl local logs [service] [options] ``` | Argument | Required | Description | | --------- | -------- | -------------------------------------------------- | | `service` | No | Service name (`api`, `web`, `worker`, `surrealdb`) | | Option | Short | Default | Description | | ---------- | ----- | ------- | ----------------------- | | `--follow` | `-f` | on | Follow log output | | `--tail` | | 100 | Number of lines to show | --- ## local reset Reset the local instance: stop containers, delete all data, and remove saved configuration. Prompts for confirmation unless `--force` is given. ```bash sibyl local reset [options] ``` | Option | Short | Default | Description | | --------- | ----- | ------- | ----------------- | | `--force` | `-f` | false | Skip confirmation | --- ## local setup Set up Claude/Codex integration: skills for Claude Code and Codex, plus Claude Code hooks (session-start and prompt injection). In development mode it symlinks; in package mode it copies. ```bash sibyl local setup [options] ``` | Option | Short | Default | Description | | ----------- | ----- | ------- | ----------------------------------------------- | | `--status` | `-s` | false | Only show current installation status | | `--snippet` | | false | Show the prompt snippet for Claude/Codex config | ## Notes - Services bind to `127.0.0.1`: web UI on `3337`, API on `3334`, SurrealDB on `8000`. - First-run setup reads `OPENAI_API_KEY` and `ANTHROPIC_API_KEY` from the environment when present; otherwise configure keys from the web UI. - `local reset` and `local stop --destroy` delete the SurrealDB volume and all data; use them deliberately. ## Related Commands - [`sibyl docker`](./docker.md) - Pinned, production-leaning Docker stack - [`sibyl service`](./service.md) - Native host daemon service files - [`sibyl doctor`](./doctor.md) - Verify health after starting - [`sibyl skill`](./skill.md) - Install the skill stub without hooks -
memory.md 16.6 KB
# memory governance Sibyl's memory loop is governed. Raw memories and reflection candidates are not written straight into the shared graph; they move through review, promotion, and audit. Agents inspect and repair source truth with `correct`; operators use the `admin memory` command family: | Command | Description | | ------------------------------- | -------------------------------------------- | | [`sibyl correct`](#correct) | Inspect or correct a raw memory source | | [`sibyl cite`](#usage-feedback) | Record material citation or misleading usage | | Command | Description | | ----------------------------------------------------------- | ---------------------------------------------------------------- | | [`sibyl admin memory audit`](#memory-audit) | Inspect memory audit receipts | | [`sibyl admin memory inspect`](#memory-inspect) | Inspect a memory source and its audit trail | | [`sibyl admin memory import-status`](#memory-import-status) | Inspect a source import receipt and its published raw memory IDs | | [`sibyl admin memory promote`](#memory-promote) | Preview or auto-review candidate promotion | | [`sibyl admin memory share`](#memory-share) | Preview memory sharing across scopes | | [`sibyl admin memory space`](#memory-space) | Memory-space inspection and preview | | [`sibyl admin memory review`](#memory-review) | Reflection review queue automation | For the dream-cycle automation that drives much of this, see [`memory-review`](#memory-review). ## correct Run `correct` without an action to inspect revisions, corrections, audits, derivations, and supersession lineage: ```bash sibyl correct raw_memory:abc123 ``` Apply the smallest correction matching what happened and provide a durable reason: ```bash sibyl correct raw_memory:abc123 --action wrong \ --reason "Contradicted by the verified configuration" sibyl correct raw_memory:abc123 --action stale \ --reason "Valid only before the v2 migration" sibyl correct raw_memory:abc123 --action duplicate \ --duplicate-of raw_memory:def456 --reason "Same decision captured twice" sibyl correct raw_memory:abc123 --action superseded \ --replacement raw_memory:def456 --reason "The newer decision replaces this one" printf '%s' "Corrected canonical body" | sibyl correct raw_memory:abc123 \ --action revise --reason "The prior wording was misleading" --expected-revision 3 ``` Every applied correction returns a mutation receipt with its operation ID, affected records, and revision. Use `--preview` to validate a mutation without applying it. The hidden `blame` alias remains available during migration, but new instructions should use `correct` for inspection. ## Usage Feedback Record positive feedback only when memory materially shaped the result: ```bash sibyl cite decision_abc raw_memory:def456 ``` Use `--misled` only when the cited memory shaped the result incorrectly. Irrelevant or unused context is not misleading: ```bash sibyl cite raw_memory:def456 --misled ``` ## Memory Scopes Raw memories and artifacts carry a scope that controls who can recall them: | Scope | Visibility | | --------- | -------------------------------------- | | `private` | The capturing principal only (default) | | `project` | Members working in a project | | `team` | A named team | | `org` | Organization-wide memory | `--scope-key` pins a scope to a specific project, team, or organization bucket. --- ## memory-audit Inspect memory audit receipts. Every governed memory action (capture, promotion, share preview, denial) writes an audit event. `memory-audit` reads that trail. ### Synopsis ```bash sibyl admin memory audit [options] ``` ### Options | Option | Short | Default | Description | | -------------- | ----- | ------- | ----------------------------- | | `--action` | `-a` | (all) | Filter by audit action | | `--actor` | | (all) | Filter by actor user ID | | `--source-id` | | (all) | Filter by source ID | | `--derived-id` | | (all) | Filter by derived ID | | `--scope` | | (all) | Filter by memory scope | | `--project` | `-p` | (all) | Filter by project ID | | `--policy` | | (all) | Filter: `allowed` or `denied` | | `--limit` | `-l` | 50 | Maximum events (1-200) | | `--json` | `-j` | false | Output as JSON | ### Examples ```bash # Recent governed memory events sibyl admin memory audit # Only denied actions sibyl admin memory audit --policy denied # Promotions by a specific actor sibyl admin memory audit --action promote --actor user_abc123 --json ``` --- ## memory-inspect Inspect a memory source and its audit trail. Given a raw memory source ID, this shows the source record together with every audit event that touched it. ### Synopsis ```bash sibyl admin memory inspect <source_id> [options] ``` ### Arguments | Argument | Required | Description | | ----------- | -------- | -------------------- | | `source_id` | Yes | Raw memory source ID | ### Options | Option | Short | Description | | -------- | ----- | -------------- | | `--json` | `-j` | Output as JSON | ### Example ```bash sibyl admin memory inspect mem_abc123def456 ``` --- ## memory-import-status Inspect a source import receipt and its published raw memory IDs. Given a source import ID, this shows the import receipt together with the raw memory IDs the import published. ### Synopsis ```bash sibyl admin memory import-status <import_id> [options] ``` ### Arguments | Argument | Required | Description | | ----------- | -------- | ---------------- | | `import_id` | Yes | Source import ID | ### Options | Option | Short | Description | | -------- | ----- | -------------- | | `--json` | `-j` | Output as JSON | ### Example ```bash sibyl admin memory import-status imp_abc123def456 ``` --- ## memory-promote Preview, apply, or auto-review candidate promotion. The target is a raw memory or a reflection candidate (a typed memory extracted by [`reflect`](./reflect.md) and routed to the review queue). Promotion moves it into the shared graph. ### Synopsis ```bash sibyl admin memory promote <candidate_id> [options] ``` ### Arguments | Argument | Required | Description | | -------------- | -------- | ------------------------------------- | | `candidate_id` | Yes | Raw memory or reflection candidate ID | ### Options | Option | Short | Description | | ------------------------ | ----- | ------------------------------------------------------- | | `--preview` | | Preview without promoting | | `--apply` | | Apply the promotion now | | `--auto` | | Auto-review and promote when safe | | `--dry-run` | | Evaluate auto-review without applying | | `--confidence-threshold` | | Override the auto-review confidence threshold (0.0-1.0) | | `--scope` | | Target memory scope | | `--scope-key` | | Target scope key | | `--domain` | `-d` | Domain/category | | `--project` | `-p` | Project ID | | `--all-projects` | | Do not auto-scope to the linked project | | `--related-to` | | Comma-separated graph IDs to relate after promotion | | `--task` | | Comma-separated task IDs to relate after promotion | | `--json` | `-j` | Output as JSON | ### Promotion Modes Exactly one of `--preview`, `--apply`, or `--auto` is required. - `--preview`: show what promotion would produce; write nothing. - `--apply`: apply the promotion now. - `--auto`: auto-review the candidate and promote it when it clears the confidence threshold. - `--dry-run`: with `--auto`, run the auto-review scoring and report the decision without applying it. ### Examples ```bash # Preview a candidate before promoting sibyl admin memory promote cand_abc123 --preview # Dry-run the auto-review decision sibyl admin memory promote cand_abc123 --dry-run # Auto-promote into a project scope when safe sibyl admin memory promote cand_abc123 --auto \ --scope project --scope-key proj_abc123 \ --confidence-threshold 0.8 ``` --- ## memory-share Preview or apply promotion-backed memory sharing. `memory-share` reports what sharing one or more raw memories into another scope would entail; add `--apply` to perform the sharing writes. ### Synopsis ```bash sibyl admin memory share <source_ids>... [options] ``` ### Arguments | Argument | Required | Description | | ------------ | -------- | ------------------------------- | | `source_ids` | Yes | Raw memory IDs to share-preview | ### Options | Option | Short | Description | | ----------------- | ----- | --------------------------------------- | | `--apply` | | Apply sharing writes | | `--preview` | | Preview without sharing | | `--target-scope` | | Intended target scope | | `--target-key` | | Target scope key | | `--recipient-org` | | Future recipient organization ID | | `--project` | `-p` | Project ID | | `--all-projects` | | Do not auto-scope to the linked project | | `--json` | `-j` | Output as JSON | ### Examples ```bash # Preview what sharing would entail sibyl admin memory share mem_abc123 mem_def456 \ --target-scope shared --preview # Apply the sharing writes sibyl admin memory share mem_abc123 mem_def456 \ --target-scope shared --apply ``` --- ## memory-space Memory-space inspection and preview commands. A memory space groups raw memory under an access boundary an agent or API key can be scoped to. ### memory-space preview-agent Preview what an agent could recall from selected memory spaces. Use this to confirm an agent's reach before granting it. #### Synopsis ```bash sibyl admin memory space preview-agent <agent_id> --space <space_id> [options] ``` #### Arguments | Argument | Required | Description | | ---------- | -------- | ------------------ | | `agent_id` | Yes | Agent principal ID | #### Options | Option | Short | Required | Description | | -------------- | ----- | -------- | ------------------------------------------- | | `--space` | | Yes | Primary memory space ID | | `--also-space` | | No | Comma-separated additional memory space IDs | | `--limit` | `-l` | No | Maximum sources (1-200, default 50) | | `--json` | `-j` | No | Output as JSON | #### Example ```bash sibyl admin memory space preview-agent agent_abc123 \ --space space_main \ --also-space space_shared,space_team \ --limit 100 ``` --- ## memory-review Memory review queue automation commands. This is the reflection dream-cycle: the automation that drains pending candidates, runs the org-scoped nightly maintenance job, and records decision receipts. | Subcommand | Description | | ----------------------------------------------- | ------------------------------------------------------------ | | [`memory-review drain`](#memory-review-drain) | Drain pending reflection candidates through automatic review | | [`memory-review dream`](#memory-review-dream) | Queue the automatic reflection dream-cycle job | | [`memory-review status`](#memory-review-status) | Show dream-cycle runs and automatic decision receipts | ### memory-review drain Drain pending reflection candidates through automatic review. By default this previews the drain; `--apply` commits safe promotions. #### Synopsis ```bash sibyl admin memory review drain [options] ``` #### Options | Option | Short | Description | | ------------------------ | ----- | --------------------------------------------------------- | | `--apply` | | Apply safe promotions instead of only previewing | | `--limit` | | Candidates to process (1-200, default 50) | | `--confidence-threshold` | | Override the auto-review confidence threshold (0.0-1.0) | | `--scope` | | Target memory scope | | `--scope-key` | | Target scope key | | `--domain` | `-d` | Domain/category | | `--project` | `-p` | Project ID | | `--all-projects` | | Do not auto-scope to the linked project | | `--related-to` | | Comma-separated graph IDs to relate after promotion | | `--task` | | Comma-separated task IDs to relate after promotion | | `--archive-exceptions` | | Archive terminal duplicate/stale exceptions when applying | | `--archive-reasons` | | Comma-separated exception reasons eligible for archive | | `--json` | `-j` | Output as JSON | #### Examples ```bash # Preview the drain sibyl admin memory review drain # Apply safe promotions and archive stale exceptions sibyl admin memory review drain --apply --archive-exceptions ``` ### memory-review dream Queue the automatic reflection dream-cycle maintenance job. The dream cycle is the org-scoped nightly pass that reflects raw sources, drains candidates, and records lifecycle findings. By default it queues a dry run; `--apply` queues a run that commits safe promotions. #### Synopsis ```bash sibyl admin memory review dream [options] ``` #### Options | Option | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------ | | `--apply` | Apply safe automatic promotions instead of a dry run | | `--source-limit` | Raw sources to process (0-100, default 20) | | `--candidate-limit` | Pending reflection candidates (0-200, default 50) | | `--archive-exceptions` | Archive terminal duplicate/stale exceptions when applying (`--keep-exceptions` to disable, default on) | | `--json` / `-j` | Output as JSON | #### Examples ```bash # Queue a dry-run dream cycle sibyl admin memory review dream # Queue an applying run with wider source coverage sibyl admin memory review dream --apply --source-limit 50 ``` ### memory-review status Show reflection dream-cycle runs and automatic decision receipts. #### Synopsis ```bash sibyl admin memory review status [options] ``` #### Options | Option | Short | Default | Description | | --------- | ----- | ------- | -------------------------- | | `--limit` | `-l` | 10 | Maximum runs/events (1-50) | | `--json` | `-j` | false | Output as JSON | #### Example ```bash sibyl admin memory review status --limit 20 ``` ## Related Commands - [`sibyl remember`](./remember.md) - Capture durable memory - [`sibyl reflect`](./reflect.md) - Produce reviewable reflection candidates - [`sibyl context`](./context.md) - Recall memory into a context pack - [`sibyl synthesis`](./synthesis.md) - Source-grounded synthesis from memory -
org.md 4.4 KB
# org Organizations. Each Sibyl organization is an isolated tenant with its own SurrealDB namespace (`org_<uuid_hex>`). `org` lists organizations, creates them, switches the active org, and manages members. ## Commands | Command | Description | | ----------------------------------- | ------------------------------ | | [`sibyl org list`](#org-list) | List organizations | | [`sibyl org create`](#org-create) | Create an organization | | [`sibyl org switch`](#org-switch) | Switch the active organization | | [`sibyl org members`](#org-members) | Manage organization members | ## Org Isolation Every graph and memory operation is scoped to an organization. Switching orgs changes the namespace the CLI reads and writes. Membership roles (`owner`, `admin`, `member`, `viewer`) govern what a user can do inside an org. --- ## org list List the organizations you belong to. ```bash sibyl org list ``` --- ## org create Create a new organization. By default the CLI switches into the new org after creating it. ### Synopsis ```bash sibyl org create --name <name> [options] ``` ### Options | Option | Short | Default | Description | | ---------- | ----- | --------- | ----------------------------------------------------- | | `--name` | `-n` | (req.) | Organization name (required) | | `--slug` | | (derived) | Optional URL slug | | `--switch` | | on | Switch into the org after creating it (`--no-switch`) | ### Example ```bash sibyl org create --name "Acme Engineering" --slug acme-eng ``` --- ## org switch Switch the active organization by slug. ### Synopsis ```bash sibyl org switch <slug> ``` ### Arguments | Argument | Required | Description | | -------- | -------- | ----------------- | | `slug` | Yes | Organization slug | ### Example ```bash sibyl org switch acme-eng ``` --- ## org members Manage organization members. | Subcommand | Description | | -------------------------- | --------------------------- | | `sibyl org members list` | List all members of an org | | `sibyl org members add` | Add a member to an org | | `sibyl org members remove` | Remove a member from an org | | `sibyl org members role` | Update a member's role | Roles: `owner`, `admin`, `member`, `viewer`. ### org members list ```bash sibyl org members list <slug> [--json] ``` | Argument | Required | Description | | -------- | -------- | ----------------- | | `slug` | Yes | Organization slug | ### org members add ```bash sibyl org members add <slug> <user_id> [options] ``` | Argument | Required | Description | | --------- | -------- | ----------------- | | `slug` | Yes | Organization slug | | `user_id` | Yes | User ID to add | | Option | Short | Default | Description | | -------- | ----- | -------- | -------------- | | `--role` | `-r` | `member` | Role to assign | ### org members remove ```bash sibyl org members remove <slug> <user_id> [options] ``` | Argument | Required | Description | | --------- | -------- | ----------------- | | `slug` | Yes | Organization slug | | `user_id` | Yes | User ID to remove | | Option | Short | Description | | --------- | ----- | ----------------- | | `--force` | `-f` | Skip confirmation | ### org members role ```bash sibyl org members role <slug> <user_id> <role> ``` | Argument | Required | Description | | --------- | -------- | ---------------------------------------------- | | `slug` | Yes | Organization slug | | `user_id` | Yes | User ID | | `role` | Yes | New role: `owner`, `admin`, `member`, `viewer` | ### Examples ```bash # List members sibyl org members list acme-eng # Add a member as an admin sibyl org members add acme-eng user_abc123 --role admin # Promote a member to admin sibyl org members role acme-eng user_abc123 admin # Remove a member without a prompt sibyl org members remove acme-eng user_abc123 --force ``` ## Related Commands - [`sibyl auth`](./auth.md) - Authentication and API keys - [`sibyl config context`](./context.md) - Bundle server, org, and project settings -
pending-writes.md 6.4 KB
# pending-writes Inspect and recover writes whose server outcome is not confirmed. The CLI keeps the request and its original idempotency key in a local directory restricted to your user. A timeout can happen after the server applies a write, so a buffered entry does not prove that the server saved nothing. ## Ownership and reauthentication New writes record a server-confirmed identity: the database instance, user, organization, and credential restrictions. Signing in again as the same user in the same organization recovers that identity. Replacing a database at the same URL, switching accounts, or selecting a different organization does not authorize replay. API keys retain their own identity and restrictions. The CLI verifies the current identity before replay. Mutations also carry the expected database instance so the server can reject a changed destination. Cached identity is used to record who owns an offline draft, never as sufficient proof to send it. A write buffered while the server is unreachable still records an owner, taken from the identity the stored login already proved for that server and credential scope. No request is made to read it. Signing in fresh clears that cache and asks the server for the identity once while the connection is up, so the first offline write after a login is not stranded. A write buffered with no login at all for its destination records why nobody owns it, and it is never reported as retrying. Servers predating this contract support replay only under the original credential lineage. Upgrade the server to recover writes across new logins. ## Inspect the queue ```bash sibyl pending-writes list sibyl pending-writes list --json ``` The list shows the target, operation, class, attempts, and the failure that parked the entry. A rejection also shows the HTTP status, the error code, and the server's own message, bounded to 200 characters. Request bodies are never printed, and a message is kept only for a rejection or a conflict, where the server is describing the request rather than itself. Each entry falls in exactly one class, and only the first moves on its own: - **retrying:** this login owns it and the destination is the current server. Replay is attempted after a successful API request, with backoff between attempts. - **needs_attention:** the server rejected it or left a conflict unresolved. Automatic replay skips it until the cause is fixed and `retry` re-enables it. - **unowned:** no credential this login can prove owns it. A rotated login, an older CLI, or a write buffered with nobody signed in all land here. Use `adopt` or `discard`. - **foreign_server:** the write targets another server URL, so no command against this one will ever send it. Select that server's context, or discard it. - **read_like:** a search buffered by an older CLI that treated it as a mutation. Re-run the command instead. - **corrupt:** the file must be repaired or explicitly discarded before it can be used. Commands report the queue at completion, and only when a person has to act. Nothing prints while every buffered write is young and owned. Writes that are failing or past a short grace period get one line. Everything parked gets one line naming the count per class. Within a verified owner or original credential lineage, an unresolved write holds later operations on the same entity. Independent writes can continue. Bulk operations form an ordering barrier because they can touch multiple entities. Explicitly selecting a later write does not bypass its unresolved predecessor. Outside task, entity, and project routes, ordering follows the first two URL path segments; different action paths do not share an ordering lane. ## Flush retryable writes ```bash sibyl pending-writes flush sibyl pending-writes flush <write-id>... ``` Flush verifies ownership and reuses the original idempotency key. The server can return its stored receipt when an earlier attempt already completed. Only a confirmed successful response removes the local entry. Rejected and uncertain outcomes preserve the payload for inspection. After resolving an attention entry's cause, explicitly re-enable it: ```bash sibyl pending-writes retry <write-id>... ``` Retry preserves the original payload, key, and failure evidence. Ownership and ordering checks still apply. A permanent rejection stays in attention if the server rejects it again. ## Recover legacy entries For old entries with no credential owner, select the original server context and run: ```bash sibyl -C <context> pending-writes adopt <write-id>... ``` `claim` is the same command under its original name. Before it does anything, it prints one line naming how many writes it will replay, to which server, as which user and organization, and which requests they are. For entries tied to an older login that is no longer available: ```bash sibyl -C <context> pending-writes adopt --unverified <write-id>... ``` The command shows the authenticated user and organization plus each selected operation and server. Confirm only when those entries belong to that account and organization. The CLI cannot prove historical ownership that was never recorded. Explicit IDs are required with `--unverified`; `--yes` supplies confirmation for operator-controlled automation. Adoption never transfers an entry that already has a verified owner. It preserves the old credential scope as recovery provenance and retries eligible claimed writes. Another server URL must be handled through its own context. ## Discard unwanted entries ```bash sibyl pending-writes discard <write-id>... sibyl pending-writes discard --read-like sibyl pending-writes discard --foreign sibyl pending-writes discard --rejected ``` Offline drafts retain their last verified owner. Replacing the database does not transfer those drafts to the new instance. Keep their payloads for inspection before deciding how to recover them. Discard permanently removes the named local copies without replay. Export or copy any payload you need before discarding it. Nothing is ever discarded on the CLI's own initiative. Each selector is explicit, and only one can be used per run. `--read-like` removes requests buffered by older CLI versions that incorrectly treated some searches as mutations. `--foreign` removes writes whose destination is not the current server. `--rejected` removes writes the server refused with a 4xx that the payload cannot pass, which a replay of the same request can never fix. -
project.md 8 KB
# project Project management commands. Projects are the top-level container for tasks and epics. ## Commands - `sibyl project list` - List all projects - `sibyl project show` - Show project details - `sibyl project create` - Create a project - `sibyl project progress` - Show project progress - `sibyl project link` - Link directory to project - `sibyl project relink` - Repair the link for the current directory - `sibyl project unlink` - Remove directory link - `sibyl project links` - List all directory links --- ## project list List all projects. ### Synopsis ```bash sibyl project list [options] ``` ### Options | Option | Short | Default | Description | | --------- | ----- | ------- | ----------- | | `--limit` | `-n` | 20 | Max results | | `--json` | `-j` | false | JSON output | | `--csv` | | false | CSV output | ### Example ```bash sibyl project list ``` Output: ``` Projects ID Name Status Description ─────────────────────────────────────────────────────────────────── proj_abc1.. Backend API active REST API for mobile and web clients proj_def2.. Mobile App active iOS and Android app proj_ghi3.. Documentation active Technical documentation site Showing 3 project(s) ``` --- ## project show Show project details with task summary. ### Synopsis ```bash sibyl project show <project_id> [options] ``` ### Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | ### Example ```bash sibyl project show proj_abc123 ``` Output: ``` Project proj_abc1 Name: Backend API Status: active Description: REST API for mobile and web clients Task Summary: todo: 12 doing: 3 blocked: 1 review: 2 done: 45 Progress: ████████████░░░░░░░░ 71% Tech Stack: typescript, express, postgresql ``` ### JSON Output ```bash sibyl project show proj_abc123 --json ``` ```json { "id": "proj_abc123", "name": "Backend API", "entity_type": "project", "description": "REST API for mobile and web clients", "metadata": { "status": "active", "tech_stack": ["typescript", "express", "postgresql"] }, "task_summary": { "total": 63, "by_status": { "todo": 12, "doing": 3, "blocked": 1, "review": 2, "done": 45 } } } ``` --- ## project create Create a new project. ### Synopsis ```bash sibyl project create --name <name> [options] ``` ### Required Options | Option | Short | Description | | -------- | ----- | ----------------------- | | `--name` | `-n` | Project name (required) | ### Options | Option | Short | Description | | --------------- | ----- | ------------------- | | `--description` | `-d` | Project description | | `--repo` | `-r` | Repository URL | | `--json` | `-j` | JSON output | ### Example ```bash sibyl project create \ --name "Backend API" \ --description "REST API for mobile and web clients" \ --repo "https://github.com/org/backend-api" ``` Output: ``` Project created: proj_abc123def456 ``` --- ## project progress Show project progress with visual breakdown. ### Synopsis ```bash sibyl project progress <project_id> [options] ``` ### Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | ### Example ```bash sibyl project progress proj_abc123 ``` Output: ``` Project Progress ████████████████████████████░░░░░░░░░░░░ 71.4% (45/63) Status Breakdown: backlog ██ 2 todo ████████████ 12 doing ███ 3 blocked █ 1 review ██ 2 done █████████████████████████████████████████████ 45 ``` ### JSON Output ```bash sibyl project progress proj_abc123 --json ``` ```json { "project_id": "proj_abc123", "total_tasks": 63, "completed": 45, "progress_percent": 71.4, "by_status": { "backlog": 2, "todo": 12, "doing": 3, "blocked": 1, "review": 2, "done": 45 } } ``` --- ## project link Link a directory to a project for automatic context. This is the key to automatic project-scoped operations. ### Synopsis ```bash sibyl project link <project_id> [options] ``` ### Options | Option | Short | Default | Description | | -------- | ----- | ------- | ---------------------- | | `--path` | `-p` | cwd | Directory path to link | ### Example ```bash cd ~/dev/backend-api sibyl project link proj_abc123 ``` Output: ``` Linked /Users/bliss/dev/backend-api -> Backend API (proj_abc123def456...) Task commands in this directory will now auto-scope to this project ``` ### Link Another Directory ```bash sibyl project link proj_xyz789 --path ~/dev/mobile-app ``` ### How It Works Once linked: ```bash cd ~/dev/backend-api sibyl task list # Only shows tasks for proj_abc123 sibyl context "work on auth" # Only loads context from proj_abc123 sibyl task create --title "Fix bug" # Creates in proj_abc123 ``` The link is stored in `~/.sibyl/config.toml`: ```toml [paths] "/Users/bliss/dev/backend-api" = "proj_abc123" "/Users/bliss/dev/mobile-app" = "proj_xyz789" ``` --- ## project relink Repair the project link for the current directory. Use this when a link points at a stale or renamed project and you want to retarget it without unlinking first. ### Synopsis ```bash sibyl project relink [options] ``` ### Options | Option | Short | Default | Description | | -------- | ----- | ------- | -------------------------------------------- | | `--id` | | (none) | Project ID, UUID, name, or slug to relink to | | `--path` | `-p` | cwd | Directory path | ### Example ```bash cd ~/dev/backend-api sibyl project relink --id backend-api ``` --- ## project unlink Remove project link from a directory. ### Synopsis ```bash sibyl project unlink [options] ``` ### Options | Option | Short | Default | Description | | -------- | ----- | ------- | ------------------------ | | `--path` | `-p` | cwd | Directory path to unlink | ### Example ```bash cd ~/dev/backend-api sibyl project unlink ``` Output: ``` Unlinked /Users/bliss/dev/backend-api ``` ### Unlink Specific Path ```bash sibyl project unlink --path ~/dev/old-project ``` --- ## project links List all directory-to-project links. ### Synopsis ```bash sibyl project links ``` ### Example ```bash sibyl project links ``` Output: ``` Project Links: * /Users/bliss/dev/backend-api -> proj_abc123def456789 /Users/bliss/dev/mobile-app -> proj_xyz789abc123456 * = current context ``` --- ## Common Workflows ### Setup New Project ```bash # 1. Create project sibyl project create --name "My New Project" --description "Project description" # Returns: proj_abc123 # 2. Link directory cd ~/dev/my-new-project sibyl project link proj_abc123 # 3. Create initial tasks sibyl task create --title "Setup repository" sibyl task create --title "Configure CI/CD" sibyl task create --title "Write initial documentation" ``` ### Multi-Project Workflow ```bash # Work on backend cd ~/dev/backend sibyl task list --status doing sibyl task complete task_abc --learnings "..." # Switch to frontend cd ~/dev/frontend sibyl task list --status todo sibyl task start task_xyz ``` ### Cross-Project Operations ```bash # Search across all projects sibyl context "authentication" --all # List all tasks (all projects) sibyl task list --all # Override the project for a single command sibyl task list --project proj_other ``` ## Related Commands - [`sibyl task list`](./task-list.md) - List tasks (respects project context) - `sibyl config context` - Manage named server, org, and project contexts - [`sibyl epic list`](./epic.md) - List epics in project -
recall.md 999 B
# recall `recall` is a hidden compatibility alias for [`sibyl context`](./context.md). New instructions and automation should use `context` directly. ```bash sibyl context "wire up the password reset endpoint" --intent build sibyl context "auth token refresh fails intermittently" --intent debug sibyl context "plan the migration" --intent plan --budget 1200 ``` ## Compatibility ```bash # Equivalent during the compatibility window sibyl recall "wire up the password reset endpoint" --intent build ``` Both routes accept the same context layers, raw-memory filters, project scoping, diary identity, JSON output, and token budget. The advertised intents are `build`, `plan`, `review`, `debug`, and `general`. ## Related Commands - [`sibyl context`](./context.md) - Load an agent-ready context pack - [`sibyl remember`](./remember.md) - Store durable memory - [`sibyl reflect`](./reflect.md) - Turn raw notes into memory candidates - [`sibyl session`](./session.md) - Package a wake-up bundle -
reflect.md 4.4 KB
# reflect Reflect raw notes into memory candidates, optionally persisting them. `reflect` takes unstructured session notes and runs them through Sibyl's extractor to produce typed memory candidates (decisions, plans, ideas, claims, and learnings) you can review or commit. ## Synopsis ```bash sibyl reflect [content] [options] ``` Content is read from stdin when the positional argument is omitted. ## Arguments | Argument | Required | Description | | --------- | -------- | -------------------------------------------- | | `content` | No | Raw notes to reflect. Reads stdin if omitted | ## Options | Option | Short | Default | Description | | ---------------- | ----- | -------------------- | ----------------------------------------------------------------------------- | | `--title` | `-t` | `Session reflection` | Source/session title | | `--intent` | `-i` | `general` | Intent: build, plan, ideate, research, review, debug, decide, learn, general | | `--domain` | `-d` | (none) | Domain/category | | `--project` | `-p` | (auto) | Project ID | | `--all-projects` | | false | Do not auto-scope to the linked project | | `--related-to` | | (none) | Comma-separated entity IDs to link persisted candidates to | | `--task` | | (none) | Comma-separated task IDs to link persisted output to | | `--active-task` | | on | When persisting, auto-link to the active task (`--no-active-task`) | | `--persist` | | false | Persist candidates into the graph | | `--source` | | on | When persisting, also store the raw notes as a session memory (`--no-source`) | | `--review` | | false | Store persisted output in the raw review queue instead of graph promotion | | `--cited` | | (none) | Comma-separated context/search IDs that informed this reflection | | `--limit` | `-l` | 12 | Maximum candidates (1-25) | | `--json` | `-j` | false | Output as JSON | ## How It Works `reflect` runs in three modes depending on flags: 1. **Preview** (default): extract candidates and print them. Nothing is written. 2. **Persist** (`--persist`): commit candidates straight into the graph as typed memories. 3. **Review** (`--persist --review`): route candidates into the raw review queue for governed promotion instead of writing directly to the graph. With `--persist`, the `--source` flag (on by default) also stores the original notes as a session memory so the extraction stays traceable to its input. ## Examples ### Preview Candidates from a Session ```bash sibyl reflect "Decided to drop the Postgres sidecar. Idea: add a freshness score to synthesis verify. Still unsure how to scope shared memory across orgs." ``` ### Reflect from stdin ```bash cat session-notes.md | sibyl reflect --title "Auth refactor session" --intent debug ``` ### Persist Candidates into the Graph ```bash sibyl reflect --persist --project proj_abc123 < notes.txt ``` ### Route Candidates to the Review Queue Use `--review` when candidates should be governed before they land in the graph. They become pending reflection candidates that `memory-promote` or `memory-review` can act on. ```bash sibyl reflect --persist --review --domain synthesis < notes.txt ``` ### JSON Output ```bash sibyl reflect "..." --json | jq '.candidates[] | {kind, title}' ``` ## Related Commands - [`sibyl remember`](./remember.md) - Capture a single durable memory directly - [`sibyl context`](./context.md) - Recall memory into an agent context - [Memory governance](./memory.md) - Promote and audit reflection candidates - [`sibyl synthesis`](./synthesis.md) - Source-grounded synthesis from memory -
remember.md 5.8 KB
# remember Remember a decision, plan, idea, claim, artifact, session, or learning. `remember` is the write side of the Sibyl memory loop. It captures a titled memory and routes it into the graph, or stores it verbatim as a raw memory or private agent diary entry. ## Synopsis ```bash sibyl remember <title> [content] [options] ``` Content is read from stdin when the positional argument is omitted. ## Arguments | Argument | Required | Description | | --------- | -------- | ----------------------------------- | | `title` | Yes | Title/name of the memory | | `content` | No | Memory body. Reads stdin if omitted | ## Options | Option | Short | Default | Description | | ------------------- | ----- | --------- | -------------------------------------------------------- | | `--content` | | (none) | Memory body (alternative to positional) | | `--content-file` | | (none) | Read content from a file | | `--max-size` | | 1048576 | Maximum content file size in bytes | | `--follow-symlinks` | | false | Allow `--content-file` to read through symlinks | | `--kind` | `-k` | `episode` | Entity type to create (see [entity](./entity.md)) | | `--domain` | `-d` | (none) | Domain/category | | `--project` | `-p` | (auto) | Project ID | | `--all-projects` | | false | Do not auto-scope to the linked project | | `--tags` | | (none) | Comma-separated tags | | `--related-to` | | (none) | Comma-separated entity IDs to connect with `RELATED_TO` | | `--task` | | (none) | Comma-separated task IDs to connect with `RELATED_TO` | | `--active-task` | | on | Auto-link to the single active task (`--no-active-task`) | | `--surface` | | `cli` | Capture surface metadata | | `--wait-searchable` | | false | Wait until the memory is persisted and retrievable | | `--json` | `-j` | false | Output as JSON | | `--raw` | | false | Store verbatim raw memory only | | `--diary` | | false | Store a private agent diary entry | | `--agent` | | (none) | Agent identity for diary entries | | `--source-id` | | (none) | Raw memory source ID | | `--scope` | | `private` | Raw memory scope | | `--scope-key` | | (none) | Project/team/org scope key | | `--pin` | | false | Exempt the memory from ordinary decay | | `--basis` | | (none) | `observed`, `inferred`, `told`, or `assumed` | | `--propose-scope` | | (none) | Nominate the memory for audited team promotion | ## Memory Kinds `remember` defaults to `episode`, but the memory loop adds first-class kinds for durable reasoning artifacts: | Kind | Use Case | | --------------- | ------------------------------------------- | | `episode` | General learning or knowledge (default) | | `decision` | A choice that was made, with rationale | | `procedure` | A repeatable implementation or runbook | | `error_pattern` | A recurring failure and its verified fix | | `rule` | A durable constraint or invariant | | `plan` | An intended sequence of work | | `idea` | An exploration or proposal not yet acted on | | `claim` | An assertion to be verified or cited later | | `artifact` | A produced output (synthesis, doc, summary) | | `session` | A session-level memory or summary | | `note` | A durable observation or breadcrumb | Compatibility kinds remain accepted for existing automation, but new agent instructions should use the compact set above. ## Examples ### Remember a Decision ```bash sibyl remember "Use SurrealDB for the unified runtime" \ "Chose SurrealDB over a Postgres+graph split. One store for graph, content, and auth removes sidecar drift and simplifies org isolation." \ --kind decision ``` ### Remember a Plan ```bash sibyl remember "Synthesis rollout plan" \ "Ship plan/draft/verify behind a flag, dogfood on docs, then expose synthesis_* MCP tools." \ --kind plan --domain synthesis ``` ### Remember from a File ```bash sibyl remember "Incident 2026-05 postmortem" --content-file ./postmortem.md --kind episode ``` ### Store a Raw Memory `--raw` skips graph extraction and stores the payload verbatim in the raw memory store. Raw memories are read back with `context --raw` and reviewed before promotion. ```bash sibyl remember "Deploy runbook" --raw --scope project --scope-key proj_abc123 ``` ### Store an Agent Diary Entry ```bash sibyl remember "Picked up the auth refactor" \ "Started on token rotation. Blocker: Redis WRONGTYPE on refresh." \ --diary --agent nova ``` ### Pipe Content from stdin ```bash git log -5 --oneline | sibyl remember "Recent auth commits" --kind episode ``` ## Related Commands - [`sibyl context`](./context.md) - Load memory back into an agent context - [`sibyl reflect`](./reflect.md) - Turn raw notes into reviewable candidates - [`sibyl capture`](./capture.md) - Quick capture without a separate title - [Memory governance](./memory.md) - Inspect, audit, and promote raw memory -
search.md 1.3 KB
# search `search` is a hidden compatibility alias for [`sibyl context`](./context.md). It now returns the same agent-ready context pack and accepts the same goal-oriented options. New instructions and automation should call `context` directly: ```bash sibyl context "implement authentication" --intent build sibyl context "debug intermittent token refresh failures" --intent debug --limit 8 sibyl context "review deployment guidance" --intent review --all ``` ## Compatibility ```bash # Equivalent during the compatibility window sibyl search "implement authentication" --intent build ``` The old graph-search grammar is not accepted by `search`. Flags such as `--type`, `--graph-only`, and `--docs-only` belonged to the pre-convergence command. Existing operator automation can use the hidden `sibyl graph-search` escape while migrating, but agent prompts should use `context`. Use `sibyl show <id>` when a returned context preview is not enough. Record material usage with `sibyl cite <id...>` or `sibyl cite <id...> --misled`. ## Related Commands - [`sibyl context`](./context.md) - Load an agent-ready context pack - [`sibyl show`](./show.md) - Retrieve full graph or raw-memory content by ID - [`sibyl remember`](./remember.md) - Store durable raw-first memory - [`sibyl correct`](./memory.md) - Inspect or correct source memory -
service.md 3.6 KB
# service Install local daemon service files. `service` writes a native user-service definition that keeps the embedded `sibyld` daemon running for your active local context: a launchd agent on macOS, a systemd user unit on Linux. It writes the file but does not start it, so you stay in control of when the daemon comes up. This is for running Sibyl directly on the host. For a containerized deployment, use [`sibyl docker`](./docker.md) or [`sibyl local`](./local.md). ## Running the Daemon Three top-level commands run the embedded `sibyld` daemon natively, without Docker: | Command | What it does | | ------------- | ------------------------------------------------- | | `sibyl serve` | Run the daemon in the foreground (Ctrl+C to stop) | | `sibyl start` | Start the daemon in the background | | `sibyl stop` | Stop the background daemon | ```bash # First-run local setup, then run in the foreground sibyl init --local sibyl serve # Or run it in the background and check health sibyl start sibyl doctor sibyl stop ``` For a daemon that survives reboots, install a user-service file with [`sibyl service install`](#service-install) below. ## Commands | Command | Description | | ------------------------------------------- | ------------------------------------------------------------- | | [`sibyl service install`](#service-install) | Write a native user-service file for the active local context | | [`sibyl service path`](#service-path) | Print the native service file path for this platform | --- ## service install Write a native user-service file for the active local context. The command prints the start command for your platform but does not run it. ```bash sibyl service install [options] ``` | Option | Short | Default | Description | | ------------- | ----- | ----------------- | ---------------------------------- | | `--host` | | `127.0.0.1` | Host to bind | | `--port` | `-p` | 3334 | Port to listen on | | `--transport` | `-t` | `streamable-http` | MCP transport | | `--force` | `-f` | false | Overwrite an existing service file | ### Examples ```bash # Install the service file for the active local context sibyl service install # Bind a custom port and overwrite an existing file sibyl service install --port 3344 --force ``` After install, start the service with the printed command: ```bash # macOS launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/tech.hyperbliss.sibyl.plist # Linux systemctl --user enable --now sibyl.service ``` --- ## service path Print the native service file path for this platform. ```bash sibyl service path ``` The path is `~/Library/LaunchAgents/tech.hyperbliss.sibyl.plist` on macOS and `~/.config/systemd/user/sibyl.service` on Linux. ## Notes - `service install` requires an active local context; switch to one with `sibyl config context use local` or create one with [`sibyl init --local`](./init.md) first. - The service launches `sibyld serve --embedded` and logs to `~/.sibyl/run/sibyld.service.log`. - Native service files are only supported on macOS and Linux. ## Related Commands - [`sibyl init`](./init.md) - Create the local context the service runs against - [`sibyl doctor`](./doctor.md) - Verify daemon health after starting the service - [`sibyl local`](./local.md) - Run a Docker-based local instance instead -
session.md 1.5 KB
# Session Bundle Package wake-up context for the current session. This command turns Sibyl's hook-era startup context into a first-class CLI surface. ## Usage ```bash sibyl session bundle sibyl session bundle "archived entity paging" sibyl session bundle --json ``` ## What It Includes - Current server and project context - Doing or blocked tasks for the current project - A few relevant decisions, plans, ideas, procedures, or other memories derived from the current task titles or your explicit query - One short "remember next" line ## Options | Option | Short | Default | Description | | ---------------- | ----- | ------- | ------------------------------------ | | `--task-limit` | - | `5` | Maximum active tasks to include | | `--memory-limit` | - | `3` | Maximum relevant memories to include | | `--all` | `-a` | false | Search across all projects | | `--json` | `-j` | false | Output machine-readable bundle JSON | ## Examples Wake up with current project context: ```bash sibyl session bundle ``` Focus the bundle on a specific topic: ```bash sibyl session bundle "backup job ids" ``` Use JSON from hooks or automation: ```bash sibyl session bundle --json | jq '.remember_next' ``` Search across all projects: ```bash sibyl session bundle --all ``` ## Related Commands - [`sibyl context`](./context.md) - Recall a goal-scoped working context pack - [`sibyl task list`](./task-list.md) - List active tasks directly -
show.md 873 B
# show Show full content for a graph entity or raw memory ID. Use this after `sibyl context`, `sibyl search`, or any command that prints an ID. The command accepts graph entity IDs, raw memory IDs, and `raw_memory:<id>` references. ## Synopsis ```bash sibyl show <id> [options] ``` ## Arguments | Argument | Required | Description | | -------- | -------- | ------------------------------ | | `id` | Yes | Entity or raw memory reference | ## Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | ## Examples ```bash # Show a graph entity from search results sibyl show plan_df925c5b6eed # Show a raw memory from search or metadata sibyl show raw_memory:1f08c55c-b67a-475b-b52b-922c675ff748 # Bare raw memory UUIDs work too sibyl show 1f08c55c-b67a-475b-b52b-922c675ff748 ``` -
skill.md 3.4 KB
# skill Install the loader skill and print bundled markdown packs. `skill` manages the Sibyl skill stub that Claude Code, Codex, and other assistants load to learn the memory loop, and it prints version-matched markdown packs straight from the installed CLI bundle. Called with no subcommand, `skill` prints the canonical loader markdown to stdout. Pass `--install` to write it into your assistant skill roots instead. ## Synopsis ```bash sibyl skill [options] sibyl skill <command> [options] ``` ## Options | Option | Short | Default | Description | | ----------- | ----- | ------- | ------------------------------------------------------- | | `--install` | | false | Install the loader skill into assistant skill roots | | `--force` | | false | Replace existing symlink or non-directory skill targets | | `--quiet` | `-q` | false | Suppress install status output | ## Commands | Command | Description | | --------------------------------------- | ---------------------------------------------------- | | [`sibyl skill install`](#skill-install) | Install the stable Sibyl skill stub into skill roots | | [`sibyl skill list`](#skill-list) | List skill packs available from this CLI version | | [`sibyl skill get`](#skill-get) | Print a version-matched markdown skill pack | Skill roots are `~/.claude/skills`, `~/.codex/skills`, and `~/.agents/skills`. --- ## skill install Install the stable Sibyl skill stub into assistant skill roots. ```bash sibyl skill install [options] ``` | Option | Short | Default | Description | | --------- | ----- | ------- | ------------------------------------------------------- | | `--force` | | false | Replace existing symlink or non-directory skill targets | | `--quiet` | `-q` | false | Suppress install status output | ### Example ```bash sibyl skill install --force ``` --- ## skill list List the skill packs bundled with this installed CLI version. ```bash sibyl skill list ``` Packs include `core`, `quick`, `workflows`, `examples`, and `migration`. --- ## skill get Print a version-matched markdown skill pack from the CLI bundle. Defaults to the `core` pack. ```bash sibyl skill get [name] ``` | Argument | Required | Default | Description | | -------- | -------- | ------- | ---------------------------------------------------- | | `name` | No | `core` | Skill pack to print (`sibyl skill list` for choices) | ### Examples ```bash # Print the core workflow pack sibyl skill get # Print the minimal subagent pack sibyl skill get quick ``` ## Notes - The stub is intentionally stable: it points assistants at the version-matched packs rather than embedding the full contract, so a CLI upgrade refreshes guidance without re-installing. - `--force` replaces existing symlinks or non-directory targets; without it, those roots are skipped. - [`sibyl doctor`](./doctor.md) checks that the installed stub matches the canonical markdown and flags stale copies. ## Related Commands - [`sibyl doctor`](./doctor.md) - Verify the skill stub is installed and current - [`sibyl update`](./update.md) - Refresh skills as part of a self-update - [`sibyl local`](./local.md) - Install skills and hooks together with `local setup` -
synthesis.md 6.4 KB
# synthesis Source-grounded synthesis commands. `synthesis` turns authorized memory into structured artifacts (documentation, summaries, briefs) where every claim traces back to a cited source. The pipeline is plan, draft, verify, and remember. ## Commands | Command | Description | | ------------------------------------------------- | ----------------------------------------------------- | | [`sibyl synthesis plan`](#synthesis-plan) | Plan source-grounded synthesis from authorized memory | | [`sibyl synthesis draft`](#synthesis-draft) | Draft a verified synthesis artifact | | [`sibyl synthesis verify`](#synthesis-verify) | Verify citation, freshness, redaction, gap coverage | | [`sibyl synthesis remember`](#synthesis-remember) | Draft, verify, and remember an artifact | ## The Synthesis Pipeline ``` plan -> draft -> verify -> remember | | | | sections artifact checks stored artifact ``` `plan` resolves which sources are authorized and proposes a section outline. `draft` produces the artifact text. `verify` runs the quality gates. `remember` chains draft, verify, and a `remember` write so a passing artifact lands in memory in one step. --- ## synthesis plan Plan source-grounded synthesis from authorized memory. ### Synopsis ```bash sibyl synthesis plan <goal> [options] ``` ### Arguments | Argument | Required | Description | | -------- | -------- | -------------- | | `goal` | Yes | Synthesis goal | ### Options | Option | Short | Default | Description | | ----------------- | ----- | --------------- | ---------------------------------------------------------- | | `--type` | | `documentation` | Output type | | `--audience` | | (none) | Intended audience | | `--depth` | | `standard` | `brief`, `standard`, or `deep` | | `--seed` | | (none) | Search seed query | | `--project` | `-p` | (auto) | Project ID | | `--all-projects` | | false | Skip cwd project scope | | `--domain` | `-d` | (none) | Domain/category | | `--entity` | | (none) | Comma-separated entity IDs | | `--decision` | | (none) | Comma-separated decision IDs | | `--task` | | (none) | Comma-separated task IDs | | `--artifact` | | (none) | Comma-separated artifact IDs | | `--section` | | (none) | Pipe-separated `Title::Prompt::sources` specs | | `--constraint` | | (none) | Comma-separated constraints | | `--max-sections` | | 6 | Maximum sections (1-12) | | `--neighborhoods` | | on | Include one-hop graph neighborhoods (`--no-neighborhoods`) | | `--json` | `-j` | false | Output full JSON | ### Examples ```bash # Plan documentation from memory sibyl synthesis plan "How Sibyl handles org isolation" # Deep brief for a specific audience sibyl synthesis plan "Synthesis verification model" \ --depth deep --audience "new engineers" # Seed retrieval and pin specific sources sibyl synthesis plan "Auth hardening summary" \ --seed "api key scopes" \ --decision dec_abc123,dec_def456 ``` --- ## synthesis draft Draft a verified synthesis artifact. Runs `plan` then produces the artifact body. ### Synopsis ```bash sibyl synthesis draft <goal> [options] ``` ### Options `draft` accepts every [`synthesis plan`](#synthesis-plan) option plus: | Option | Default | Description | | ---------- | ---------- | -------------------- | | `--format` | `markdown` | `markdown` or `json` | ### Examples ```bash # Draft a markdown artifact sibyl synthesis draft "How Sibyl handles org isolation" # Draft as structured JSON sibyl synthesis draft "Synthesis verification model" --format json ``` --- ## synthesis verify Verify synthesis citation, freshness, redaction, and gap coverage. Use this to gate an artifact before it is published or remembered. ### Synopsis ```bash sibyl synthesis verify <goal> [options] ``` ### Options `verify` accepts the same options as [`synthesis plan`](#synthesis-plan). ### Verification Checks | Check | What it confirms | | --------- | -------------------------------------------------- | | Citation | Every claim is backed by a cited source | | Freshness | Cited sources are recent enough for the goal | | Redaction | No hidden-context or out-of-scope memory leaked in | | Gap | Planned sections are actually covered by the draft | ### Example ```bash sibyl synthesis verify "How Sibyl handles org isolation" --json | jq '.checks' ``` --- ## synthesis remember Draft, verify, and remember a synthesis artifact in one step. The artifact is stored as an `artifact` memory only when verification passes. ### Synopsis ```bash sibyl synthesis remember <goal> [options] ``` ### Options `remember` accepts every [`synthesis draft`](#synthesis-draft) option plus: | Option | Default | Description | | ------------- | --------- | ----------------------------- | | `--scope` | `private` | Artifact memory scope | | `--scope-key` | (none) | Artifact scope key | | `--tags` | (none) | Comma-separated artifact tags | ### Example ```bash sibyl synthesis remember "Auth hardening summary" \ --depth deep \ --scope project --scope-key proj_abc123 \ --tags "auth,summary" ``` ## Related Commands - [`sibyl remember`](./remember.md) - Capture durable memory - [`sibyl context`](./context.md) - Recall memory into a context pack - [Memory governance](./memory.md) - Audit and inspect memory sources - [`sibyl context`](./context.md) - Semantic search across the graph -
task-create.md 5.4 KB
# task create Create a new task in a project. ## Synopsis ```bash sibyl task create --title <title> [options] ``` ## Required Options | Option | Description | | --------- | --------------------- | | `--title` | Task title (required) | ::: warning Note Unlike some CLIs, the title is passed as `--title`, not as a positional argument. This is intentional for clarity and to avoid ambiguity with descriptions. ::: ## Options | Option | Short | Default | Description | | --------------- | ----- | ---------- | -------------------------------------------------- | | `--title` | | (required) | Task title | | `--project` | `-p` | (auto) | Project ID (auto-resolves from linked path) | | `--description` | `-d` | (none) | Task description | | `--priority` | | `medium` | Priority: critical, high, medium, low, someday | | `--complexity` | | `medium` | Complexity: trivial, simple, medium, complex, epic | | `--assignee` | `-a` | (none) | Initial assignee | | `--epic` | `-e` | (none) | Epic ID to group under | | `--feature` | `-f` | (none) | Feature area | | `--tags` | | (none) | Comma-separated tags | | `--tech` | | (none) | Comma-separated technologies | | `--depends-on` | | (none) | Comma-separated task IDs this task depends on | | `--json` | `-j` | false | JSON output | ## Priority Levels | Priority | Use Case | | ---------- | ------------------------------------ | | `critical` | Production issues, blocking bugs | | `high` | Important features, significant bugs | | `medium` | Normal priority work (default) | | `low` | Nice to have, minor improvements | | `someday` | Ideas for later, backlog parking | ## Complexity Levels | Complexity | Typical Effort | | ---------- | --------------------------------- | | `trivial` | < 1 hour, config changes | | `simple` | 1-4 hours, well-understood | | `medium` | 1-2 days, some unknowns (default) | | `complex` | 3-5 days, significant unknowns | | `epic` | > 1 week, should be broken down | ## Examples ### Basic Task ```bash sibyl task create --title "Fix login button alignment" ``` Output: ``` Task created: task_abc123def456 ``` ### With Description and Priority ```bash sibyl task create \ --title "Implement password reset flow" \ --description "Add forgot password endpoint, email service integration, and reset form" \ --priority high ``` ### Full Example ```bash sibyl task create \ --title "Add rate limiting to API" \ --description "Implement rate limiting using Redis. Start with 100 req/min per user." \ --priority high \ --complexity medium \ --assignee "nova" \ --epic epic_security \ --feature "api" \ --tags "security,performance" \ --tech "redis,express" ``` ### Specify Project If not in a linked directory, specify the project: ```bash sibyl task create \ --title "Update documentation" \ --project proj_abc123 ``` ### JSON Output ```bash sibyl task create --title "New feature" --json ``` ```json { "id": "task_xyz789abc123", "name": "New feature", "entity_type": "task", "metadata": { "status": "todo", "priority": "medium", "complexity": "medium", "project_id": "proj_abc123" } } ``` ## Project Resolution The project is determined in this order: 1. `--project` / `-p` option 2. Linked directory (`sibyl project link`) 3. Error if none found ```bash # Link directory first (once) sibyl project link proj_abc123 # Now create without --project sibyl task create --title "Fix bug" # Uses proj_abc123 ``` ## Dependencies Create tasks that depend on other tasks: ```bash sibyl task create \ --title "Deploy to production" \ --depends-on "task_abc123,task_def456" ``` ## Integration with Epics Create tasks under an epic: ```bash # First, create or find your epic sibyl epic list --project proj_abc # Create task under epic sibyl task create \ --title "Implement OAuth2" \ --epic epic_security_improvements ``` ## Scripting Example Create multiple tasks from a file: ```bash # tasks.txt (one title per line) # Fix login bug # Update user model # Add tests while read title; do sibyl task create --title "$title" --project proj_abc done < tasks.txt ``` ## Common Pitfalls ### Missing --title ```bash # Wrong - positional arguments not supported sibyl task create "Fix bug" # Correct sibyl task create --title "Fix bug" ``` ### No Project Context ```bash # Error: No project specified and no linked project for current directory sibyl task create --title "Fix bug" # Solutions: sibyl task create --title "Fix bug" --project proj_abc # Explicit sibyl project link proj_abc # Link directory first ``` ## Related Commands - [`sibyl task list`](./task-list.md) - List tasks - [`sibyl task show`](./task-lifecycle.md) - View task details - [`sibyl task start`](./task-lifecycle.md) - Start working on task - [`sibyl epic create`](./epic.md) - Create epics to group tasks - [`sibyl project link`](./project.md) - Link directory to project -
task-lifecycle.md 13.8 KB
# Task Lifecycle Commands Commands for managing task state transitions: show, start, block, unblock, review, complete, archive, update. ## Task States ``` backlog -> todo -> doing -> review -> done | v blocked -> doing (unblock) done/any -> archived ``` ## Optimistic Concurrency Every state-transition verb (`start`, `block`, `unblock`, `review`, `complete`, `update`, `archive`) accepts `--expected-revision <n>`. When set, the command is rejected if the task's current revision no longer matches, so concurrent agents working the same task fail fast instead of clobbering each other's changes. Read the current revision from `sibyl task show <task_id> --json`. --- ## task show Show detailed task information. ### Synopsis ```bash sibyl task show <task_id> [options] ``` ### Arguments | Argument | Required | Description | | --------- | -------- | ----------------------------- | | `task_id` | Yes | Task ID or unambiguous prefix | ### Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | Task ID arguments accept an unambiguous prefix, so `sibyl task show task_abc1` resolves as long as only one task matches. ### Example ```bash sibyl task show <task_id> ``` Output: ``` Task task_abc1 Title: Fix authentication bug Status: doing Priority: high Project: proj_xyz7... Assignees: nova, bliss Description: JWT token refresh fails silently after Redis TTL expires. Feature: authentication Branch: fix/auth-token-refresh Tech: redis, express, jwt ``` --- ## task start Start working on a task. Moves status to `doing`. ### Synopsis ```bash sibyl task start <task_id> [options] ``` ### Options | Option | Short | Description | | --------------------- | ----- | ---------------------------- | | `--assignee` | `-a` | Assign to this person | | `--expected-revision` | | Reject a stale task revision | | `--json` | `-j` | JSON output | ### Example ```bash sibyl task start task_abc123 ``` Output: ``` Task started: task_abc1... Branch: fix/auth-token-refresh ``` ### With Assignee ```bash sibyl task start task_abc123 --assignee "nova" ``` ### Branch Name Generation When a task is started, Sibyl automatically generates a branch name based on the task title: - `Fix authentication bug` -> `fix/authentication-bug` - `Add user profile page` -> `add/user-profile-page` The branch name is stored in `metadata.branch_name`. --- ## task block Mark a task as blocked with a reason. ### Synopsis ```bash sibyl task block <task_id> --reason <reason> [options] ``` ### Required Options | Option | Short | Description | | ---------- | ----- | ------------------------- | | `--reason` | `-r` | Blocker reason (required) | ### Options | Option | Short | Description | | --------------------- | ----- | ---------------------------- | | `--expected-revision` | | Reject a stale task revision | | `--json` | `-j` | JSON output | ### Example ```bash sibyl task block task_abc123 --reason "Waiting for API spec from backend team" ``` Output: ``` Task blocked: task_abc1... ``` ### Common Block Reasons ```bash sibyl task block task_abc --reason "Waiting for design review" sibyl task block task_abc --reason "Depends on task_xyz" sibyl task block task_abc --reason "Need clarification from PM" sibyl task block task_abc --reason "Infrastructure not ready" ``` --- ## task unblock Resume a blocked task. Moves status back to `doing`. ### Synopsis ```bash sibyl task unblock <task_id> [options] ``` ### Options | Option | Short | Description | | --------------------- | ----- | ---------------------------- | | `--expected-revision` | | Reject a stale task revision | | `--json` | `-j` | JSON output | ### Example ```bash sibyl task unblock task_abc123 ``` Output: ``` Task unblocked: task_abc1... ``` --- ## task review Submit a task for review. Moves status to `review`. ### Synopsis ```bash sibyl task review <task_id> [options] ``` ### Options | Option | Short | Description | | --------------------- | ----- | ---------------------------- | | `--pr` | | Pull request URL | | `--commits` | `-c` | Comma-separated commit SHAs | | `--expected-revision` | | Reject a stale task revision | | `--json` | `-j` | JSON output | ### Example ```bash sibyl task review task_abc123 --pr "https://github.com/org/repo/pull/42" ``` Output: ``` Task submitted for review: task_abc1... ``` ### With Commits ```bash sibyl task review task_abc123 \ --pr "https://github.com/org/repo/pull/42" \ --commits "abc123,def456,ghi789" ``` --- ## task complete Complete a task and optionally capture learnings. ### Synopsis ```bash sibyl task complete <task_id> [options] ``` ### Options | Option | Short | Default | Description | | ------------------------ | ----- | ------- | ----------------------------------------------------------- | | `--hours` | `-h` | (none) | Actual hours spent | | `--learnings` / `--note` | `-l` | (none) | Key learnings (creates an episode) | | `--learnings-file` | | (none) | Read learnings from a file | | `--max-size` | | 1048576 | Maximum learnings file size in bytes | | `--follow-symlinks` | | false | Allow `--learnings-file` to read through symlinks | | `--cited` | | (none) | Comma-separated context/search IDs that informed completion | | `--expected-revision` | | (none) | Reject a stale task revision | | `--json` | `-j` | false | JSON output | ### Basic Completion ```bash sibyl task complete task_abc123 ``` Output: ``` Task completed: task_abc1... ``` ### With Hours Tracking ```bash sibyl task complete task_abc123 --hours 4.5 ``` ### With Learnings ```bash sibyl task complete task_abc123 \ --learnings "JWT refresh tokens fail silently when Redis TTL expires. Root cause: token service doesn't handle WRONGTYPE error. Fix: Add try/except with token regeneration fallback." ``` Output: ``` Task completed: task_abc1... Learning episode created from task ``` ::: tip Capture Knowledge Use `--learnings` to capture non-obvious solutions, gotchas, or insights. This creates a linked episode in the knowledge graph. ::: ### Full Example ```bash sibyl task complete task_abc123 \ --hours 6.5 \ --learnings "PostgreSQL connection pooling was the root cause. PgBouncer with transaction mode resolved the issue. Key insight: always check pool_mode when debugging connection timeouts." ``` ### Learnings from a File For longer write-ups, read learnings from a file instead of an inline string: ```bash sibyl task complete task_abc123 --hours 6.5 --learnings-file ./task-notes.md ``` ### With Citations Credit the memories that materially informed the completion. IDs come from `sibyl context` or search results: ```bash sibyl task complete task_abc123 --cited "mem_abc123,mem_def456" ``` --- ## task archive Archive task(s). Supports bulk operations via stdin. ### Synopsis ```bash sibyl task archive <task_id> [options] sibyl task archive --stdin [options] ``` ### Options | Option | Short | Description | | --------------------- | ----- | ------------------------------------- | | `--reason` | `-r` | Archive reason | | `--yes` | `-y` | Skip confirmation (required for bulk) | | `--stdin` | | Read task IDs from stdin | | `--expected-revision` | | Reject a stale task revision | | `--json` | `-j` | JSON output | ### Single Task ```bash sibyl task archive task_abc123 --yes ``` ### With Reason ```bash sibyl task archive task_abc123 --reason "Duplicate of task_xyz" --yes ``` ### Bulk Archive ```bash # Archive all done tasks sibyl task list --status done --json | jq -r '.[].id' | sibyl task archive --stdin --yes # Archive old todo tasks sibyl task list --status todo -q "deprecated" --json | jq -r '.[].id' | sibyl task archive --stdin --yes ``` ::: warning Bulk Safety Bulk archive requires `--yes` flag for safety. ::: --- ## task update Update task fields directly. ### Synopsis ```bash sibyl task update <task_id> [options] ``` ### Options | Option | Short | Description | | --------------------- | ----- | -------------------------------------------------- | | `--status` | `-s` | Status: todo, doing, blocked, review, done | | `--priority` | `-p` | Priority: critical, high, medium, low, someday | | `--complexity` | | Complexity: trivial, simple, medium, complex, epic | | `--title` | | Task title | | `--description` | `-d` | Task description/content | | `--assignee` | `-a` | Assignee | | `--epic` | `-e` | Epic ID to group under | | `--feature` | `-f` | Feature area | | `--tags` | | Comma-separated tags (replaces existing) | | `--tech` | | Comma-separated technologies (replaces existing) | | `--add-dep` | | Comma-separated task IDs to add as dependencies | | `--remove-dep` | | Comma-separated task IDs to remove as dependencies | | `--expected-revision` | | Reject a stale task revision | | `--json` | `-j` | JSON output | To archive a task, use [`task archive`](#task-archive) rather than `task update --status`. ### Examples ```bash # Change priority sibyl task update task_abc123 --priority critical # Reassign sibyl task update task_abc123 --assignee "bliss" # Update multiple fields sibyl task update task_abc123 \ --priority high \ --complexity complex \ --tags "security,urgent" # Move to epic sibyl task update task_abc123 --epic epic_security # Update title sibyl task update task_abc123 --title "Fix JWT token refresh (URGENT)" ``` --- ## task note Add a note to a task. Content can be passed positionally, piped via `-`, or read from a file. ### Synopsis ```bash sibyl task note <task_id> [content] [options] ``` ### Arguments | Argument | Required | Description | | --------- | -------- | ----------------------------- | | `task_id` | Yes | Task ID or unambiguous prefix | | `content` | No | Note content or `-` for stdin | ### Options | Option | Short | Default | Description | | ------------------------- | ----- | ------- | ----------------------------------------------- | | `--content-file` | | (none) | Read note content from a file | | `--max-size` | | 1048576 | Maximum content file size in bytes | | `--follow-symlinks` | | false | Allow `--content-file` to read through symlinks | | `--assistant` / `--agent` | | false | Mark as assistant-authored (default: user) | | `--author` | `-a` | (none) | Author name/identifier | | `--json` | `-j` | false | JSON output | ### Examples ```bash # Add user note sibyl task note task_abc123 "Found the root cause - Redis connection timeout" # Add assistant note sibyl task note task_abc123 "Implementing the fix now" --assistant --author claude # Note from stdin git log -1 --format=%B | sibyl task note task_abc123 - ``` The top-level [`sibyl note`](./remember.md) command wraps this: pass a task ID and it adds a task note, pass free text and it captures a note memory. --- ## task notes List notes for a task. ### Synopsis ```bash sibyl task notes <task_id> [options] ``` ### Options | Option | Short | Default | Description | | --------- | ----- | ------- | ----------- | | `--limit` | `-n` | 20 | Max results | | `--json` | `-j` | false | JSON output | ### Example ```bash sibyl task notes task_abc123 ``` Output: ``` user 2024-01-15 10:30:00 Found the root cause - Redis connection timeout assistant claude 2024-01-15 10:35:00 Implementing the fix now. Will add retry logic. user 2024-01-15 11:00:00 Fix deployed to staging, testing now. 3 note(s) ``` --- ## Workflow Example A typical task workflow: ```bash # 1. Pick a task to work on sibyl task list --status todo --priority high sibyl task show task_abc123 # 2. Start the task sibyl task start task_abc123 # 3. Add progress notes sibyl task note task_abc123 "Investigated the issue, found root cause" # 4. If blocked sibyl task block task_abc123 --reason "Need API spec from backend" # 5. When unblocked sibyl task unblock task_abc123 # 6. Submit for review sibyl task review task_abc123 --pr "https://github.com/org/repo/pull/42" # 7. Complete with learnings sibyl task complete task_abc123 \ --hours 4 \ --learnings "Key insight: Always check Redis connection pool settings" ``` ## Related Commands - [`sibyl task list`](./task-list.md) - List tasks - [`sibyl task create`](./task-create.md) - Create new task - [`sibyl context`](./context.md) - Recall a context pack before starting a task -
task-list.md 7.5 KB
# task list List tasks with optional filters. The workhorse command for task management. ## Synopsis ```bash sibyl task list [options] ``` ## Options ### Filtering | Option | Short | Description | | -------------- | ----- | -------------------------------------------------- | | `--query` | `-q` | Search query (semantic search on name/description) | | `--status` | `-s` | Filter by status (comma-separated) | | `--priority` | | Filter by priority (comma-separated) | | `--complexity` | | Filter by complexity (comma-separated) | | `--feature` | `-f` | Filter by feature area | | `--tags` | | Filter by tags (comma-separated, matches ANY) | | `--project` | `-p` | Project ID | | `--epic` | `-e` | Epic ID | | `--no-epic` | | Tasks without an epic | | `--assignee` | `-a` | Filter by assignee | | `--all` | `-A` | Ignore context, list from all projects | ### Pagination | Option | Short | Default | Description | | ---------- | ----- | ------- | --------------------------------- | | `--limit` | `-n` | 50 | Max results (max: 200) | | `--offset` | | 0 | Skip first N results | | `--page` | | (none) | Page number (1-based, uses limit) | ### Output | Option | Short | Description | | -------- | ----- | ----------------------------------------------- | | `--json` | `-j` | JSON output | | `--csv` | | CSV output | | `--wide` | | Render a wide task table without title wrapping | ## Status Values | Status | Description | | ---------- | ----------------------- | | `backlog` | Not yet planned | | `todo` | Planned, ready to start | | `doing` | In progress | | `blocked` | Blocked by something | | `review` | In review | | `done` | Completed | | `archived` | Archived | ## Priority Values | Priority | Description | | ---------- | -------------------- | | `critical` | Production issues | | `high` | Important work | | `medium` | Normal priority | | `low` | Nice to have | | `someday` | Future consideration | ## Complexity Values | Complexity | Description | | ---------- | ----------- | | `trivial` | < 1 hour | | `simple` | 1-4 hours | | `medium` | 1-2 days | | `complex` | 3-5 days | | `epic` | > 1 week | ## Examples ### Basic Listing ```bash # All tasks in current project sibyl task list # All tasks across all projects sibyl task list --all ``` ### Filter by Status ```bash # Single status sibyl task list --status todo # Multiple statuses (comma-separated) sibyl task list --status todo,doing # Active tasks (not done/archived) sibyl task list --status todo,doing,blocked,review ``` ### Filter by Priority ```bash # High priority only sibyl task list --priority high # Critical and high sibyl task list --priority critical,high ``` ### Filter by Complexity ```bash # Quick wins sibyl task list --complexity trivial,simple # Large tasks that need attention sibyl task list --complexity complex,epic ``` ### Semantic Search Use `-q` for semantic search on task names and descriptions: ```bash sibyl task list -q "authentication" sibyl task list -q "database migration" --status todo ``` ### Filter by Tags Match tasks with ANY of the specified tags: ```bash sibyl task list --tags "security" sibyl task list --tags "security,performance" ``` ### Filter by Epic ```bash # Tasks in a specific epic sibyl task list --epic epic_abc123 # Tasks without any epic (orphans) sibyl task list --no-epic ``` ### Filter by Assignee ```bash sibyl task list --assignee "nova" sibyl task list --assignee "bliss" --status doing ``` ### Filter by Feature ```bash sibyl task list --feature "api" sibyl task list --feature "auth" --priority high ``` ### Combined Filters Filters are combined with AND logic: ```bash # High priority todo tasks with security tag sibyl task list --status todo --priority high --tags security # My blocked tasks sibyl task list --assignee "nova" --status blocked ``` ### Pagination ```bash # First 20 tasks sibyl task list --limit 20 # Second page (tasks 21-40) sibyl task list --limit 20 --page 2 # Or using offset sibyl task list --limit 20 --offset 20 ``` ## Output Formats ### Table (Default) ```bash sibyl task list --status todo ``` ``` Tasks ID Title Status Priority Assignees ─────────────────────────────────────────────────────────────────────────── task_abc1.. Fix authentication bug todo high nova task_def2.. Update user documentation todo medium - task_ghi3.. Add rate limiting todo high bliss, nova Showing 3 task(s) ``` ### JSON ```bash sibyl task list --status todo --json ``` ```json [ { "id": "task_abc123", "name": "Fix authentication bug", "type": "task", "metadata": { "status": "todo", "priority": "high", "assignees": ["nova"], "project_id": "proj_xyz789" } }, ... ] ``` ### CSV ```bash sibyl task list --status todo --csv ``` ```csv id,title,status,priority,project,assignees task_abc123,Fix authentication bug,todo,high,proj_xyz789,nova task_def456,Update user documentation,todo,medium,proj_xyz789, task_ghi789,Add rate limiting,todo,high,proj_xyz789,"bliss,nova" ``` ## Common Workflows ### Daily Standup ```bash # What am I working on? sibyl task list --assignee "$(whoami)" --status doing # What's blocked? sibyl task list --status blocked # What's ready for me? sibyl task list --assignee "$(whoami)" --status todo --priority critical,high ``` ### Sprint Planning ```bash # Unassigned todo tasks sibyl task list --status todo --assignee "" # High priority backlog sibyl task list --status backlog --priority critical,high # Tasks without epics sibyl task list --no-epic --status todo ``` ### Review Tasks ```bash # Tasks ready for review sibyl task list --status review # My tasks in review sibyl task list --status review --assignee "nova" ``` ### Export for Reports ```bash # Export all done tasks this sprint sibyl task list --status done --csv > sprint_completed.csv # Export for analysis sibyl task list --json | jq 'group_by(.metadata.status) | map({status: .[0].metadata.status, count: length})' ``` ## Project Context By default, `task list` is scoped to the current project context: ```bash # Uses linked project or active context sibyl task list # Explicit project sibyl task list --project proj_abc123 # All projects sibyl task list --all ``` ## Pagination Details - Default limit: 50 - Maximum limit: 200 - Use `--page` for convenience or `--offset` for precise control ``` Showing 1-50 of 127+ task(s) (--page 2 for more) ``` ## Related Commands - [`sibyl task show`](./task-lifecycle.md) - View task details - [`sibyl task create`](./task-create.md) - Create new task - [`sibyl task start`](./task-lifecycle.md) - Start working on task - [`sibyl context`](./context.md) - Broader semantic search -
team.md 4.3 KB
# team Team memory management. Teams group users inside an organization, carry their own team memory space, and can be granted access to projects as a unit. ## Commands - `sibyl team list` - List teams in the active organization - `sibyl team create` - Create a team and its team memory space - `sibyl team add-member` - Add or update a team member - `sibyl team remove-member` - Remove a team member - `sibyl team link-project` - Grant a team access to a project - `sibyl team unlink-project` - Remove a team's project access --- ## team list List teams in the active organization. ### Synopsis ```bash sibyl team list [options] ``` ### Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | ### Example ```bash sibyl team list ``` --- ## team create Create a team and its team memory space. ### Synopsis ```bash sibyl team create <name> [options] ``` ### Arguments | Argument | Required | Description | | -------- | -------- | ----------- | | `name` | Yes | Team name | ### Options | Option | Short | Description | | --------------- | ----- | ---------------- | | `--slug` | | Stable team slug | | `--description` | `-d` | Team description | | `--json` | `-j` | JSON output | ### Examples ```bash # Create a team sibyl team create "Platform" # Create with a stable slug and description sibyl team create "Platform" --slug platform \ --description "Owns infra, CI, and shared tooling" ``` --- ## team add-member Add or update a team member. ### Synopsis ```bash sibyl team add-member <team_id> <user_id> [options] ``` ### Arguments | Argument | Required | Description | | --------- | -------- | --------------- | | `team_id` | Yes | Team ID or slug | | `user_id` | Yes | User UUID | ### Options | Option | Short | Default | Description | | -------- | ----- | -------- | ----------- | | `--role` | `-r` | `member` | Team role | | `--json` | `-j` | false | JSON output | ### Example ```bash sibyl team add-member platform 1f08c55c-b67a-475b-b52b-922c675ff748 ``` Running `add-member` again for the same user updates their team role. --- ## team remove-member Remove a team member. ### Synopsis ```bash sibyl team remove-member <team_id> <user_id> [options] ``` ### Arguments | Argument | Required | Description | | --------- | -------- | --------------- | | `team_id` | Yes | Team ID or slug | | `user_id` | Yes | User UUID | ### Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | ### Example ```bash sibyl team remove-member platform 1f08c55c-b67a-475b-b52b-922c675ff748 ``` --- ## team link-project Grant a team access to a project. ### Synopsis ```bash sibyl team link-project <team_id> <project_id> [options] ``` ### Arguments | Argument | Required | Description | | ------------ | -------- | -------------------------------- | | `team_id` | Yes | Team ID or slug | | `project_id` | Yes | Project UUID or graph project ID | ### Options | Option | Short | Default | Description | | -------- | ----- | --------------------- | -------------------------------- | | `--role` | `-r` | `project_contributor` | Project role granted to the team | | `--json` | `-j` | false | JSON output | ### Example ```bash sibyl team link-project platform proj_abc123 ``` --- ## team unlink-project Remove a team's project access. ### Synopsis ```bash sibyl team unlink-project <team_id> <project_id> [options] ``` ### Arguments | Argument | Required | Description | | ------------ | -------- | -------------------------------- | | `team_id` | Yes | Team ID or slug | | `project_id` | Yes | Project UUID or graph project ID | ### Options | Option | Short | Description | | -------- | ----- | ----------- | | `--json` | `-j` | JSON output | ### Example ```bash sibyl team unlink-project platform proj_abc123 ``` --- ## Related Commands - [`sibyl org`](./org.md) - Organizations and member management - [`sibyl project`](./project.md) - Project management and directory linking - [Memory governance](./memory.md) - Memory spaces, sharing, and audit -
update.md 2.1 KB
# update Check for and apply Sibyl updates. `update` upgrades the CLI, pulls newer Docker container images, and refreshes Claude/Codex skills and hooks. It only manages easy-install deployments installed via `uv tool`; when run from a source checkout it tells you to `git pull` and re-run `moon run install-dev` instead. Called with no flags, `update` checks every component, shows a status panel, and prompts before applying changes. Scope it to one component with `--cli`, `--containers`, or `--skills`. ## Synopsis ```bash sibyl update [options] ``` ## Options | Option | Short | Default | Description | | -------------- | ----- | ------- | ----------------------------------- | | `--check` | `-c` | false | Only check for updates, don't apply | | `--cli` | | false | Only update the CLI | | `--containers` | | false | Only update Docker containers | | `--skills` | | false | Only update skills and hooks | | `--yes` | `-y` | false | Skip the confirmation prompt | When none of `--cli`, `--containers`, or `--skills` is given, all three are considered. ## Examples ```bash # Check what's available without changing anything sibyl update --check # Apply all available updates without prompting sibyl update --yes # Update only the CLI sibyl update --cli # Refresh only skills and hooks sibyl update --skills ``` ## Notes - The CLI version check compares the installed `sibyl-dev` against PyPI; the container check compares local and remote image digests for the managed compose stack under `~/.sibyl`. - A successful CLI upgrade re-installs the skill stub automatically, so guidance stays version-matched. - In development mode (skills symlinked, or run from the Sibyl repo) `update` exits early with the source-update instructions; nothing is changed. ## Related Commands - [`sibyl skill`](./skill.md) - Install or refresh the skill stub directly - [`sibyl local`](./local.md) - Manage the local Docker instance - [`sibyl docker`](./docker.md) - Manage a self-hosted Docker deployment
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.