Metadata-Version: 2.4
Name: sibyl-dev
Version: 0.6.0
Summary: CLI for Sibyl knowledge graph and task workflow
Project-URL: Homepage, https://github.com/hyperb1iss/sibyl
Project-URL: Repository, https://github.com/hyperb1iss/sibyl
Author-email: Stefanie Jane <stef@hyperbliss.tech>
License-Expression: Apache-2.0
Keywords: cli,knowledge-graph,mcp,tasks
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: httpx>=0.27
Requires-Dist: pyjwt>=2.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: sibyl-core
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: typer>=0.20.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# Sibyl CLI

Command-line interface for Sibyl. REST API client with Rich terminal output, designed for humans,
external assistants, and scripts.

## Quick Reference

```bash
# Install
uv tool install sibyl-dev     # or: moon run cli:install

# Configure
sibyl config set server.url http://localhost:3334/api
sibyl auth login

# Link to project (scopes all commands)
sibyl project link <project_id>
```

## Core Commands

```bash
sibyl search "query"                    # Semantic search
sibyl recall "goal"                     # Agent-ready context before work
sibyl add "title" "content"             # Add knowledge
sibyl capture "content"                 # Quick capture from the CLI
sibyl remember "title" "content" --kind decision # Agent memory capture
sibyl reflect "raw notes" --persist     # Extract candidates and preserve raw session source
sibyl session bundle                    # Wake up with active context
sibyl task list --status todo,doing     # List tasks
sibyl task start <id>                   # Start task
sibyl task complete <id> --learnings "..." # Complete with learnings
```

## All Commands

| Command    | Purpose                                                                                             |
| ---------- | --------------------------------------------------------------------------------------------------- |
| `health`   | Check API connectivity and health                                                                   |
| `search`   | Semantic search                                                                                     |
| `recall`   | Agent-ready Markdown or JSON context before work                                                    |
| `add`      | Add knowledge                                                                                       |
| `capture`  | Quick capture from CLI arguments or stdin                                                           |
| `remember` | Capture decisions, plans, ideas, claims, artifacts, and session memory                              |
| `reflect`  | Extract reviewable candidates from raw notes, optionally preserving the raw session source          |
| `stats`    | Show knowledge graph statistics                                                                     |
| `version`  | Show CLI version information                                                                        |
| `task`     | Task lifecycle (list, show, create, start, block, unblock, review, complete, archive, update, note) |
| `epic`     | Epic management (list, start, complete, roadmap)                                                    |
| `project`  | Project management (list, link, create)                                                             |
| `archive`  | Browse archived raw captures                                                                        |
| `session`  | Package wake-up context for a session or agent                                                      |
| `entity`   | Entity CRUD                                                                                         |
| `explore`  | Graph navigation (related, traverse, dependencies, path)                                            |
| `crawl`    | Documentation sources, crawling, and graph linking                                                  |
| `debug`    | Debug tools for development                                                                         |
| `dev`      | Devcontainer shell and lifecycle commands                                                           |
| `auth`     | Login, logout, API keys                                                                             |
| `org`      | Organization switching, member management                                                           |
| `config`   | Configuration                                                                                       |
| `context`  | Multi-server context management                                                                     |
| `local`    | Manage a local Docker-based Sibyl instance                                                          |
| `logs`     | Tail server logs                                                                                    |
| `update`   | Update Sibyl components                                                                             |

## Output Formats

```bash
sibyl task list              # Table output (default)
sibyl task list --json       # JSON for scripts
sibyl task list --csv        # Spreadsheets
```

## Source Ingestion

```bash
sibyl crawl list
sibyl crawl add "https://nextjs.org/docs" --include "docs/**"
sibyl crawl ingest <source_id>
sibyl crawl documents list --source <source_id>
```

`--include` is the preferred spelling for crawl filters. `--pattern` still works for backward
compatibility.

## Capture And Archive

```bash
sibyl recall "ship the SurrealDB-native memory path" --intent build
sibyl capture "Redis TTL mismatch caused the stale auth token bug"
sibyl remember "Token TTL decision" "Keep refresh token TTL longer than access token TTL." --kind decision --domain auth
sibyl remember "Worker routing decision" "Verifier agents run after non-trivial patches." --kind decision --task task_abc
echo "Raw planning notes..." | sibyl reflect --title "Planning session" --persist --task task_abc
sibyl archive list --surface cli
sibyl archive show <capture_id>
```

In a linked project, `sibyl remember` also links to the single active `doing` task when exactly one
exists. Use `--task` for explicit links or `--no-active-task` to capture project memory without a
task edge. Persisted `sibyl reflect` output follows the same task-linking rules for its raw session
source and extracted candidates.

`sibyl reflect` accepts either an argument or stdin. By default, `--persist` writes extracted
candidates and keeps the raw notes as a `session` source for provenance. Add `--no-source` when the
raw transcript is too noisy or sensitive, but the extracted candidates should still be saved.

Persisted reflect output prints the source ID when one is stored, the candidate count, and each
persisted candidate ID:

```bash
cat session-notes.md | sibyl reflect --title "Build checkpoint" --intent build --persist
cat session-notes.md | sibyl reflect --title "Private checkpoint" --persist --no-source
```

## Context System

```bash
# Override for single command
sibyl --context myproject task list
SIBYL_CONTEXT=myproject sibyl task list

# Priority: --context flag > SIBYL_CONTEXT env > active context > path link
```

## Development

```bash
moon run cli:lint         # Ruff check
moon run cli:typecheck    # ty
moon run cli:test         # Tests
```

## SilkCircuit Colors

Terminal output uses the SilkCircuit palette:

- `#e135ff` Electric Purple: Headers
- `#80ffea` Neon Cyan: Interactions
- `#ff6ac1` Coral: Data/IDs
- `#50fa7b` Success Green
- `#ff6363` Error Red

## Dependencies

Depends on `sibyl-core` for shared models.
