CLI reference

Running xynthis with no subcommand opens an interactive REPL on a fresh session. Every invocation accepts a global --llm <provider>/<model> 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

xynthis chat "message" [--session <id>] [--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 <id> 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

xynthis resume [--id <session-id>] [--last]

Resumes a REPL session. Without --id or --last, picks the most recent.

sessions

xynthis sessions <list|show|delete|archive|summarize|extract>

Subcommand	What it does
`list`	List all saved sessions, most recent first
`show <id>`	Dump a session’s full message history as JSON
`delete <id>`	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

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

xynthis checkpoints <list|resume|prune|workspace-list|workspace-rollback|workspace-snapshot|workspace-diff>

A checkpoint is saved after every tool-call iteration, so an interrupted long plan can continue where it left off. list [--session <id>] [--top-k 20] shows recent checkpoints; resume <id> "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 <sha> [--paths ...] (whole tree, or just the listed files), workspace-snapshot [--label manual], and workspace-diff <sha>.

watch

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

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

xynthis recall "query"

Hits the brain’s L0-L3 layered retriever directly, bypassing the agent.

remember

xynthis remember "text"

Stores a free-form note directly into the brain.

ingest

xynthis ingest <messages|reminders|calendar>

Ingests external sources into the brain as perceptions with cursor tracking, so re-running is cheap. macOS only. messages [--since <hours>] [--limit N] [--db <path>] [--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

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

xynthis confirm <fact_id>
xynthis why <fact_id>

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

xynthis corpus add <path> [--name <n>] [--mask <glob>] [--ast | --regex] [--no-watch]
xynthis corpus list
xynthis corpus remove <name>
xynthis corpus update [<name>]
xynthis corpus watch <name> <on|off>
xynthis corpus context set <name> "<text>"
xynthis corpus context check
xynthis corpus status [<name>]

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

xynthis code scan <path> [--replace] [--max-files N] [--max-triples N] [--label <name>]

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

xynthis models <list|set|add|remove|test|status>

Subcommand	What it does
`list [--all]`	List configured providers; `--all` includes built-ins not yet configured
`set <target>`	Set the active target: `anthropic`, `openai/gpt-4o`, `ollama/llama3.3`
`add <provider> [--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 <provider>`	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

xynthis login <provider>

Interactive API key setup for a single provider (anthropic, openai, ollama, groq, and so on).

auth

xynthis auth <scan|apply>

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

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 <list\|show\|forget\|clear>`	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 <list\|show\|forget\|clear\|where>`	Brain-owned execution memory: typed, tier-promoted records surfaced as advisory hints at turn start
`xynthis skills <list\|search\|show\|where\|bootstrap>`	The skill library: technique docs the agent consults on demand. `bootstrap [--force]` materializes the bundled skills to `~/.xynthis/skills/<name>/SKILL.md` for editing
`xynthis persona <show\|build\|clear>`	The condensed user persona block. `build [--top-k 30]` regenerates it from recalled facts
`xynthis cortex <show\|refresh\|clear>`	The pre-synthesized situation bulletin at `~/.xynthis/cortex.json`. Injected into the system prompt when `XYNTHIS_CORTEX=on`
`xynthis extensions <list\|show>`	External MCP/webhook extension manifests under `~/.xynthis/extensions/`

Automation

recipe

xynthis recipe <list|show|run|new>

Reusable task templates. run <name> --param key=value executes one with parameters; new <name> scaffolds a YAML file at ~/.xynthis/recipes/<name>.yaml.

schedule

xynthis schedule <list|add|remove|run>

Cron-scheduled recipe runs. add <name> --cron "0 9 * * *" --recipe <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

xynthis serve [--port 3939] [--ui-dir <path>]

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.

llm

xynthis llm <status|dream|generate|eval|bitdelta-eval>

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 <ckpt>] [--target adapter|student] runs the 1-bit quantization promotion gate on a checkpoint.

browser

xynthis browser <status|open|screenshot|tabs|text>

Direct browser control with no agent turn. open <url> 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

xynthis tool list
xynthis tool <name> --args '<json>'

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.

Getting started

Core concepts

Guides

On-device model

Reference

Chat and sessions

chat

resume

sessions

search

checkpoints

watch

Memory

ask

recall

remember

ingest

status, kg-health, identity, health

confirm and why

Corpus and code

corpus

code

Models and auth

models

auth

doctor and config

Agent stores

Automation

recipe

schedule

Services

serve

llm

browser

tool

​Chat and sessions

​chat

​resume

​sessions

​search

​checkpoints

​watch

​Memory

​ask

​recall

​remember

​ingest

​status, kg-health, identity, health

​confirm and why

​Corpus and code

​corpus

​code

​Models and auth

​models

​login

​auth

​doctor and config

​Agent stores

​Automation

​recipe

​schedule

​Services

​serve

​llm

​browser

​tool

Chat and sessions

chat

resume

sessions

search

checkpoints

watch

Memory

ask

recall

remember

ingest

status, kg-health, identity, health

confirm and why

Corpus and code

corpus

code

Models and auth

models

login

auth

doctor and config

Agent stores

Automation

recipe

schedule

Services

serve

llm

browser

tool