Commands

Complete reference for all Sidecar CLI commands. Each command includes what it does, when to use it, and a usage example.

Stable JSON contract

All commands that accept --json return a consistent envelope treated as a public integration contract:

 { "ok": true, "version": "1.0", "command": "task add", "data": { ... }, "errors": [] } 

version is the JSON contract version — stable across CLI and DB schema changes.

Project Decisions Work Logs Tasks Notes Sessions Artifacts Preferences Summary Events Export UI

Project

sidecar init

sidecar init [--force] [--name <project-name>] [--json]

Initialize Sidecar in the current directory. Creates .sidecar/ (database, config, preferences, AGENTS.md, summary.md), plus AGENTS.md and CLAUDE.md at the repo root. Use --force to overwrite existing Sidecar-managed files.

When:

Once per project, at the start.

Example

$ sidecar init --name my-project

sidecar status

sidecar status

Show a quick overview of the project: name, record counts, last activity.

When:

When you want a health check on the project's memory.

Example

$ sidecar status

sidecar context

sidecar context [--limit <n>] [--format text|markdown|json]

Output structured context: recent decisions, open tasks, recent worklogs, notes. The primary way to orient yourself — or an agent — at the start of a session.

When:

Always at the start of a session.

Example

$ sidecar context --format markdown

sidecar recent

sidecar recent [--limit N]

Show the most recent records across all types, ordered by time.

When:

When you want a quick timeline of recent activity.

Example

$ sidecar recent --limit 10

sidecar capabilities

sidecar capabilities [--json]

List available Sidecar commands and features. The --json output is a strong discovery surface for agents and tooling, including cli_version, json_contract_version, features, and full command/subcommand/options metadata with JSON support indicators.

When:

Rarely needed by humans. Essential for agent bootstrapping and external tooling integration.

Example

$ sidecar capabilities --json

Decisions

sidecar decision record

 sidecar decision record --title "<title>" --summary "<summary>" [--details "<details>"] [--by human|agent] [--json] 

Record an architectural or design decision with a title and a short explanation of why it was made. Use --details for longer context.

When:

Whenever a meaningful design or architecture choice is made.

Example

 $ sidecar decision record \
    --title "Use SQLite for local storage" \
    --summary "Simple, zero-config, works offline — right for v1" 

Work Logs

sidecar worklog record

 sidecar worklog record --done "<summary>" [--goal "<goal>"] [--files a,b] [--risks "<text>"] [--next "<text>"] [--by human|agent] [--json] 

Record a log of completed work: what you set out to do, what got done, and which files changed. Optionally note risks and next steps.

When:

At the end of a meaningful unit of work or a session.

Example

 $ sidecar worklog record \
    --goal "Add task support" \
    --done "Implemented add/list/done commands" \
    --files src/tasks.ts,src/cli.ts \
    --by agent 

Tasks

sidecar task add

 sidecar task add "<title>" [--description "<text>"] [--priority low|medium|high] [--by human|agent] [--json] 

Add a follow-up task to the project. Useful for capturing work that should happen later without losing track of it.

When:

When you notice something that needs doing but you're not doing it right now.

Example

$ sidecar task add "Add import/export support" --priority medium

sidecar task list

sidecar task list [--status open|done|all] [--format table|json]

List tasks, optionally filtered by status.

When:

To see what follow-up work is outstanding.

Example

$ sidecar task list --status open

sidecar task done

sidecar task done <id>

Mark a task as completed.

When:

When you've finished a task that was recorded with sidecar task add.

Example

$ sidecar task done 42

Notes

sidecar note

sidecar note "<text>" [--by agent]

Record a short note — an observation, warning, or thought that doesn't fit neatly into another record type.

When:

For lightweight, freeform capture. Not everything needs to be a decision or worklog.

Example

$ sidecar note "Auth module is fragile — avoid changing token format"

Sessions

sidecar session start

sidecar session start [--actor human|agent] [--name "<actor-name>"] [--json]

Start a work session. Groups subsequent records under a shared session. Use --actor to tag who is running the session.

When:

When starting a focused work block, especially for agent sessions.

Example

$ sidecar session start --actor agent --name codex

sidecar session end

sidecar session end [--summary "<summary>"]

End the current session and optionally record a summary of what happened.

When:

At the end of a session started with sidecar session start.

Example

$ sidecar session end --summary "Refactored token validation, tests passing"

sidecar session current

sidecar session current

Show the currently active session, if any.

When:

To check whether a session is active.

Example

$ sidecar session current

sidecar session verify

sidecar session verify

Verify the integrity of the current session's records.

When:

Rarely needed. Useful for diagnostics.

Example

$ sidecar session verify

Artifacts

sidecar artifact add

 sidecar artifact add <path> [--kind file|doc|screenshot|other] [--note "<text>"] [--json] 

Attach a file or path to the project as a tracked artifact. Useful for referencing outputs, screenshots, or generated files alongside your records.

When:

When a file produced during work should be noted in project memory.

Example

 $ sidecar artifact add dist/report.pdf --kind doc --note "Generated audit report" 

sidecar artifact list

sidecar artifact list [--json]

List all tracked artifacts for the project.

When:

To review what files have been linked to project memory.

Example

$ sidecar artifact list

Preferences

sidecar preferences show

sidecar preferences show [--json]

Display the current project preferences. Use --json to get a stable machine-readable response for scripts and agents.

When:

To review what conventions and preferences are stored, or to read them programmatically.

Example

$ sidecar preferences show --json

sidecar preferences edit

sidecar preferences edit

Open the preferences file in your default editor.

When:

To update multiple preferences at once.

Example

$ sidecar preferences edit

sidecar preferences set

sidecar preferences set <key> <value>

Set a single preference by key.

When:

To update a specific preference without opening the editor.

Example

$ sidecar preferences set language TypeScript

Summary

sidecar summary refresh

sidecar summary refresh

Regenerate the project summary from all recent records and write it to .sidecar/summary.md.

When:

After completing meaningful work, especially at the end of a session.

Example

$ sidecar summary refresh

Events

sidecar event add

 sidecar event add --type <type> [--title <title>] [--summary <text>] [--created-by <who>] [--source <source>] [--json-input <json>] [--stdin] [--json] 

A generic validated ingest path for external tools, scripts, and agents to write Sidecar events without direct database access. Supports three mutually exclusive input modes: structured flags, raw JSON (--json-input), or piped STDIN JSON (--stdin). Supported types: note, decision, worklog, task_created, task_completed, summary_generated. Validation rules: note/worklog/task_created/task_completed require summary; decision requires title + summary; summary_generated has no required fields. Defaults: created_by = system, source = cli.

When:

When external tools, automations, or agents need to write Sidecar events through a validated interface rather than direct CLI commands.

Example

 $ sidecar event add \
    --type decision \
    --title "Use SQLite" \
    --summary "Simple local storage for v1" \
    --created-by agent \
    --json

# Raw JSON input
sidecar event add --json-input '{"type":"note","summary":"Captured context"}' --json

# STDIN
cat event.json | sidecar event add --stdin --json 

Export

sidecar export

 sidecar export [--format json|jsonl] [--limit <n>] [--type <type>] [--since <iso-date>] [--until <iso-date>] [--output <path>] 

Export Sidecar project memory for external systems, backups, or pipelines. --format json: Full object export with project, preferences, sessions, tasks, artifacts, and events. Shape: { "version": "1.0", "project": {...}, "preferences": {...}, "events": [...] } --format jsonl: Events-only stream, one JSON object per line. Shape: { "version": "1.0", "record_type": "event", "project_id": 1, "data": {...} } Output directories are created automatically when using --output.

When:

To back up project memory, pipe Sidecar data into external systems, or generate event streams for analysis.

Example

 $ sidecar export --format json --output ./exports/sidecar.json

sidecar export --format jsonl --since 2026-01-01 > events.jsonl

sidecar export --format json --type decision --limit 50 

UI

sidecar ui

sidecar ui [--port <number>]

Start a local web dashboard for the current project. Opens a browser UI where you can browse decisions, work logs, tasks, notes, and sessions without using the CLI. Runs entirely on localhost — no data leaves your machine.

When:

When you want a visual overview of your project memory, or to share context with teammates who prefer a UI over the terminal.

Example

$ sidecar ui