> ## Documentation Index > Fetch the complete documentation index at: https://docs.xynthis.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Every xynthis subcommand, grouped by what it operates on. Running `xynthis` with no subcommand opens an interactive REPL on a fresh session. Every invocation accepts a global `--llm /` flag (or the `XYNTHIS_LLM_OVERRIDE` env var) that forces a specific LLM target for that run without writing to `config.toml`. ## Chat and sessions ### chat ```bash theme={null} xynthis chat "message" [--session ] [--new] [--verbose] [--no-app] ``` Runs one agent turn against the active LLM, prints the result, and exits. By default it appends to the current session (the one you last chatted with or resumed), so consecutive `chat` calls remember each other. `--new` starts a fresh session; `--session ` targets a specific one. `--verbose` prints raw tool-call output alongside the final answer. On macOS, `chat` launches the menu-bar app and a background daemon so the GUI shows live agent activity; `--no-app` (or `XYNTHIS_NO_APP=1`) runs headless. ### resume ```bash theme={null} xynthis resume [--id ] [--last] ``` Resumes a REPL session. Without `--id` or `--last`, picks the most recent. ### sessions ```bash theme={null} xynthis sessions ``` | Subcommand | What it does | | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `list` | List all saved sessions, most recent first | | `show ` | Dump a session's full message history as JSON | | `delete ` | Delete a session file | | `archive [--older-than-days 30] [--run]` | Move old sessions into `~/.xynthis/archive`. Dry run by default; `--run` executes | | `summarize [id] [--protect-head 2] [--protect-tail 10] [--window-size 12] [--dry-run]` | Compress the middle of a long session into one summary message, in place | | `extract [id] [--max 2] [--dry-run]` | LLM-extract durable facts from a session and store them in the brain | ### search ```bash theme={null} xynthis search "query" [--index] [--top-k 10] [--semantic] ``` Full-text search across every saved session. First use needs `xynthis search index` to build the FTS5 database; the index then auto-updates on ingest. `--semantic` switches to vector search through the brain's index, which matches meaning rather than literal words and requires the brain to be running. ### checkpoints ```bash theme={null} xynthis checkpoints ``` A checkpoint is saved after every tool-call iteration, so an interrupted long plan can continue where it left off. `list [--session ] [--top-k 20]` shows recent checkpoints; `resume "next message"` continues from one; `prune [--days 14]` deletes old ones. The `workspace-*` subcommands manage filesystem snapshots taken before destructive tool calls: `workspace-list`, `workspace-rollback [--paths ...]` (whole tree, or just the listed files), `workspace-snapshot [--label manual]`, and `workspace-diff `. ### watch ```bash theme={null} xynthis watch [--format pretty|jsonl] ``` Subscribes to the agent event stream and prints each event as it fires. Useful while another xynthis process is running, such as the app. ## Memory ### ask ```bash theme={null} xynthis ask "question" [--top-k 3] [--threshold 0.5] ``` Answers a question directly from brain memory with no LLM call: zero tokens, millisecond latency. Best for factoid lookups. Results below `--threshold` carry a low-confidence warning suggesting `xynthis chat` instead. ### recall ```bash theme={null} xynthis recall "query" ``` Hits the brain's L0-L3 layered retriever directly, bypassing the agent. ### remember ```bash theme={null} xynthis remember "text" ``` Stores a free-form note directly into the brain. ### ingest ```bash theme={null} xynthis ingest ``` Ingests external sources into the brain as perceptions with cursor tracking, so re-running is cheap. macOS only. `messages [--since ] [--limit N] [--db ] [--reset-cursor]` reads iMessage history from `~/Library/Messages/chat.db` (requires Full Disk Access for the `xynthis` binary). `reminders [--reset-cursor]` ingests every open Apple Reminder. `calendar [--window-days 14] [--reset-cursor]` ingests upcoming Apple Calendar events. Once ingested, ordinary `recall` finds the content. ### status, kg-health, identity, health ```bash theme={null} xynthis status # brain status and counters xynthis kg-health # knowledge-graph integrity audit (counts only) xynthis identity # identity snapshot: mood, interactions, personality xynthis health # full stack health check ``` ### confirm and why ```bash theme={null} xynthis confirm xynthis why ``` `confirm` cryptographically attests that a recalled fact is correct: it signs the fact with the local Ed25519 identity at `~/.xynthis/bmc/identity.ed25519` and appends a row to the append-only Merkle log at `~/.xynthis/bmc/witness.log`. Fact ids appear in `recall` responses. `why` prints the full audit trail for a confirmed fact (signed payload, Ed25519 signature, RFC-6962 inclusion proof), verifiable offline against the signer's public key alone. ## Corpus and code ### corpus ```bash theme={null} xynthis corpus add [--name ] [--mask ] [--ast | --regex] [--no-watch] xynthis corpus list xynthis corpus remove xynthis corpus update [] xynthis corpus watch xynthis corpus context set "" xynthis corpus context check xynthis corpus status [] ``` Folder-as-corpus ingestion with AST chunking, BLAKE3 dedup, and auto-watch. `add` indexes a folder as a named collection (name defaults to the folder's basename) and watches it for changes unless `--no-watch` is passed. `update` re-indexes one collection or all. `context set` attaches a plain-English description that travels with every recall hit from that collection; `context check` lists collections with no context set. ### code ```bash theme={null} xynthis code scan [--replace] [--max-files N] [--max-triples N] [--label ] ``` Walks a repo, AST-parses every supported file, and ingests typed `code:*` triples into the brain's knowledge graph. `--replace` wipes prior code-scan triples first. Defaults: 10,000 files, 50,000 triples. ## Models and auth ### models ```bash theme={null} xynthis models ``` | Subcommand | What it does | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `list [--all]` | List configured providers; `--all` includes built-ins not yet configured | | `set ` | Set the active target: `anthropic`, `openai/gpt-4o`, `ollama/llama3.3` | | `add [--model M] [--api-key K] [--base-url U]` | Register a provider; prompts for the API key unless `--api-key` (or `XYNTHIS_API_KEY`) is given | | `remove ` | Remove a provider and drop its API key | | `test [target]` | Probe a provider with a tiny completion call | | `status` | Show the active target and every configured provider | ### login ```bash theme={null} xynthis login ``` Interactive API key setup for a single provider (`anthropic`, `openai`, `ollama`, `groq`, and so on). ### auth ```bash theme={null} xynthis auth ``` `scan` prints every LLM credential the scanner can detect on this machine (Codex and Claude OAuth sessions, local Ollama or LM Studio servers, env-var API keys) without modifying config. `apply [--force]` writes the findings into `~/.xynthis/config.toml` and `~/.xynthis/auth.json`, picking the highest-ranked available provider as active unless the current one still works. ### doctor and config ```bash theme={null} xynthis doctor # diagnose config / auth / binary issues xynthis config # inspect config file paths and contents ``` ## Agent stores These subcommands inspect the state the agent accumulates as it works. | Command | What it manages | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `xynthis lessons ` | The failure-to-correction store at `~/.xynthis/lessons.json`. Strong lessons (seen 3+ times) hard-block their failing approach in the agent's gating loop, so trimming this store changes runtime behavior | | `xynthis exec ` | Brain-owned execution memory: typed, tier-promoted records surfaced as advisory hints at turn start | | `xynthis skills ` | The skill library: technique docs the agent consults on demand. `bootstrap [--force]` materializes the bundled skills to `~/.xynthis/skills//SKILL.md` for editing | | `xynthis persona ` | The condensed user persona block. `build [--top-k 30]` regenerates it from recalled facts | | `xynthis cortex ` | The pre-synthesized situation bulletin at `~/.xynthis/cortex.json`. Injected into the system prompt when `XYNTHIS_CORTEX=on` | | `xynthis extensions ` | External MCP/webhook extension manifests under `~/.xynthis/extensions/` | ## Automation ### recipe ```bash theme={null} xynthis recipe ``` Reusable task templates. `run --param key=value` executes one with parameters; `new ` scaffolds a YAML file at `~/.xynthis/recipes/.yaml`. ### schedule ```bash theme={null} xynthis schedule ``` Cron-scheduled recipe runs. `add --cron "0 9 * * *" --recipe [--param k=v]` binds a cron expression to a recipe. `run` starts the scheduler loop in the foreground; wire it into launchd or a dedicated terminal for always-on scheduling. ## Services ### serve ```bash theme={null} xynthis serve [--port 3939] [--ui-dir ] ``` Starts the local HTTP daemon that the app and other clients talk to. Binds to `127.0.0.1` only. See the [HTTP API reference](/reference/http-api). ### llm ```bash theme={null} xynthis llm ``` Controls Xynthis's own on-device model. `status` shows adapter/student training state and the active teacher. `dream [--size small|medium|large]` runs one full learning cycle (SFT + distillation + eval); it blocks until done, typically 1-5 minutes on CPU. `generate "prompt"` runs the trained student (requires a prior `dream`). `eval` prints a teacher-vs-student perplexity report. `bitdelta-eval [--path ] [--target adapter|student]` runs the 1-bit quantization promotion gate on a checkpoint. ### browser ```bash theme={null} xynthis browser ``` Direct browser control with no agent turn. `open ` navigates and also perceives the page into the brain. `screenshot [--path P] [--full]` captures the active tab. `tabs` lists open tabs. `text [--max-chars 2000]` extracts the visible body text. ### tool ```bash theme={null} xynthis tool list xynthis tool --args '' ``` Direct dispatch into the agent's tool registry. Skill scripts invoke this to call back into xynthis tools mid-execution. Hidden from `--help`; intended for skill and tooling integration, not interactive use.