Todos and scratchpads from the CLI

The solo todos and solo scratchpads groups give scripts and terminal sessions project-scoped commands for common todo and scratchpad workflows. Both groups are project-scoped, so every command requires --project-id.

All commands accept --json for machine-readable output. Run solo projects list to find project IDs.

Todos#

solo todos list --project-id <id> [filters...] [--json]
solo todos get <id> --project-id <id> [--json]
solo todos create --project-id <id> --title <title> [--body <body> | --body-file <path|->] [--priority <priority>] [--tag <tag> ...] [--json]
solo todos update <id> --project-id <id> [--title <title>] [--body <body> | --body-file <path|->] [--priority <priority>] [--status <status>] [--tag <tag> ...] [--json]
solo todos delete <id> --project-id <id> [--force] [--json]
solo todos complete <id> --project-id <id> [--release-lock true|false] [--json]
solo todos incomplete <id> --project-id <id> [--release-lock true|false] [--json]

Filtering the list#

todos list supports the CLI filters below. --status accepts one status per command. --is-blocked tests whether a todo has unresolved blockers; the CLI does not expose the app's separate Blocking filter for active todos that block other work.

# Open, high-priority, unblocked work in project 2
solo todos list --project-id 2 --status open --priority high --is-blocked false
 
# Everything tagged "bug", newest first
solo todos list --project-id 2 --tag bug --sort created-desc

Creating and updating#

--title is required when creating. The priority defaults to medium. Tags set with --tag are normalized to lowercase; on create they are added, and on update they replace the todo's existing tags.

The body can come from three places:

• --body <text> for inline text.
• --body-file <path> to read from a file.
• --body-file - to read from stdin.

# Quick todo
solo todos create --project-id 2 --title "Fix flaky login test" --priority high --tag bug
 
# Longer body piped from stdin
git log --oneline -10 | solo todos create --project-id 2 \
  --title "Review recent commits" --body-file -
 
# Move a todo into progress and retag it
solo todos update 14 --project-id 2 --status in_progress --tag bug --tag urgent

Completing#

complete marks a todo done; incomplete moves a completed todo back to open. By default, both commands also release your actor's coordination lock on the todo, which matters when agents and scripts share a todo list. Pass --release-lock false to keep the lock.

solo todos complete 14 --project-id 2 --release-lock true

delete removes a todo permanently. It's non-interactive; a --force flag is accepted for compatibility but not required.

Scratchpads#

solo scratchpads list --project-id <id> [--tag <tag>] [--query <query>] [--include-archived] [--offset <n>] [--limit <n>] [--json]
solo scratchpads read <id> --project-id <id> [--mode full|content|headings|section] [--section-heading <heading>] [--offset <n>] [--limit <n>] [--json]
solo scratchpads create --project-id <id> --name <name> (--content <text> | --content-file <path|->) [--tag <tag> ...] [--json]
solo scratchpads update <id> --project-id <id> --expected-revision <n> [--name <name>] [--content <text> | --content-file <path|->] [--tag <tag> ...] [--json]
solo scratchpads append <id> --project-id <id> (--content <text> | --content-file <path|->) --expected-revision <n> [--newline] [--json]
solo scratchpads rename <id> --project-id <id> --name <name> --expected-revision <n> [--json]
solo scratchpads archive <id> --project-id <id> [--json]
solo scratchpads unarchive <id> --project-id <id> [--json]
solo scratchpads delete <id> --project-id <id> --expected-revision <n> (--confirm | --force) [--json]

Listing and reading#

list shows active scratchpads by default; add --include-archived to see archived ones too. Filter with --tag (repeatable) and --query.

read supports four modes:

# Skim a long scratchpad's structure, then read one section
solo scratchpads read 5 --project-id 2 --mode headings
solo scratchpads read 5 --project-id 2 --mode section --section-heading "Open questions"
 
# Page through a long scratchpad 100 lines at a time
solo scratchpads read 5 --project-id 2 --offset 0 --limit 100

Writing with revision checks#

Scratchpads use optimistic concurrency so multiple writers (you, scripts, agents) don't overwrite each other. Every write — update, append, rename, and delete — requires --expected-revision <n> matching the scratchpad's current revision, which you can get from list or read (in --json output). If the revision has moved on, the command fails instead of clobbering someone else's change; re-read and retry.

Content comes from --content <text>, --content-file <path>, or --content-file - for stdin. On append, add --newline to insert a newline before the appended text. Tags passed with --tag are normalized to lowercase; on update they replace existing tags.

# Create a scratchpad from a command's output
npm audit | solo scratchpads create --project-id 2 --name "audit-results" --content-file -
 
# Append a note (current revision is 3)
solo scratchpads append 5 --project-id 2 --expected-revision 3 \
  --newline --content "- [ ] follow up on the flaky test"

Archiving and deleting#

archive hides a scratchpad from the default list without losing it; unarchive brings it back. delete is permanent and requires --expected-revision plus --confirm:

solo scratchpads delete 5 --project-id 2 --expected-revision 4 --confirm

Related pages#

• JSON output and scripting — envelopes, exit codes, and jq recipes
• Todo agent tools and scratchpad agent tools — the MCP equivalents for agents