CLI

🇧🇷 Português · 🇬🇧 English

Complete reference for every squire subcommand. The dispatcher is the bash script squire (repo root); each subcommand is a cmd_<name> function there. For tasks, it delegates to tasks_cli.py.

Tip: run squire help or squire <cmd> --help to see the in-terminal summary. This page is more detailed, with examples and expected output.

Execution: run · bg · resume · dry
Observation: status · log
Control: kill · unlock
Recovery: unblock · reset
Tasks: tasks list|add|edit|rm|split|plan
Project: new · projects · rm
Budget: budget · budget set · budget reset
Help

Execution

`squire run <project>`

Runs the main loop in foreground. Acquires the session lock, reads the checkpoint, and processes all pending tasks in order.

Flag	Description
`--quiet`	Suppress instruction/response preview (`┊` markers)
`--dry-run`	Simulate without calling backends (shortcut: `squire dry`)
`--resume`	Resume from checkpoint (shortcut: `squire resume`)

Example:

$ squire run orchestrator-dashboard
→ Iniciando squire para 'orchestrator-dashboard'...
[14:22:01] → Sessão iniciada: sess-20260511-1422-a3f4c1
[14:22:01] → Projeto: Orchestrator Dashboard (orchestrator-dashboard)
[14:22:01] → ==================================================
[14:22:01] → Task [task-001]: Setup Next.js scaffolding
[14:22:01] → ==================================================
[14:22:01] → Inner loop: Setup Next.js scaffolding (tentativa 1/10)
...
[14:24:33] ✓ Task concluída: [task-001] Setup Next.js scaffolding ($0.045)

Logs are in Portuguese — squire is a Portuguese-primary project. The CLI accepts the same flags regardless of language.

See also: squire bg, squire resume, Tasks.

`squire bg <project>`

Like run but in background via nohup, with stdout redirected to /tmp/squire.log. Follow with squire log.

$ squire bg orchestrator-dashboard
→ Iniciando 'orchestrator-dashboard' em background → /tmp/squire.log
✓ Rodando com PID 28471
  Acompanhe com: squire log

`squire resume <project> [bg]`

Resumes an interrupted session from the checkpoint. Add bg to resume in background.

$ squire resume orchestrator-dashboard
→ Retomando 'orchestrator-dashboard' do checkpoint...
[14:35:12] → session_resumed
[14:35:12] → Cursor: task-003, step=homologation, attempt 2/5

Remark: if the session crashed mid-Claude-call, the checkpoint repositions before the mechanical gate. You don't pay for the failed call — RateLimiter.refund handles it when applicable. See Cost and Budget.

`squire dry <project>`

Shortcut for squire run --dry-run. Shows what it would do without invoking any backend or spending budget. Useful for inspecting the cursor before resuming.

Observation

`squire status [<project>]`

State summary in four blocks:

Active session — lock holder, PID, or "Nenhuma sessão ativa"
Projects — for each project, status + done/total task count
Rate limit — calls in current window + time until reset
Budget — today's spend + configured cap + ≥75% warning flag

$ squire status
=== Estado do squire ===

✓ Sessão ativa: sess-20260511-1422-a3f4c1 (PID 28471)

=== Projetos ===
  orchestrator-dashboard  status=implementing  tasks=4/11
  pilotinho               status=completed     tasks=8/8

=== Rate limit ===
  orchestrator-dashboard: 3/10 calls  (janela reseta em 18.4min)

=== Budget ===
  Hoje: $1.247 / $10.00  (12% usado)  |  tokens: 24,381

`squire log`

tail -f /tmp/squire.log — useful when running in background. Blocks until Ctrl+C.

$ squire log
[14:42:08] → Rodada 2/5 — inner loop: [task-004] Add CommitLog component
[14:42:08] →   ┊→ ## Task: Add CommitLog component
...

Control

`squire kill`

Kills the active session's process (SIGTERM, then SIGKILL after 1s) and removes the lock. Use when the session is stuck and not responding to Ctrl+C.

$ squire kill
⚠ Encerrando PID 28471...
✓ Processo encerrado.
✓ Lock removido.

Warning

kill is brutal. To stop gracefully, use Ctrl+C in the terminal where squire run is running — squire releases the lock correctly and writes recovery.resume_action = "continue" to the checkpoint, leaving everything ready for squire resume.

`squire unlock`

Removes a residual session.lock left by a crash (without killing a process). Use when squire status shows "Lock residual encontrado (processo morto)".

$ squire unlock
✓ Lock removido.

Recovery

`squire unblock <project> [task-id …]`

Marks blocked tasks (those that hit max_homologation_attempts) back to pending. Keeps already-written code in the repo. Without task-id, unblocks all blocked tasks. Clears rejection_summaries and no_progress_streak to prevent immediate loop-detection retriggering.

$ squire unblock orchestrator-dashboard task-005
  ✓ task-005 → pending  (Add commit log empty state)

1 task(s) desbloqueada(s).

See also: squire reset (more aggressive, discards code).

`squire reset <project> [task-id …]`

Resets tasks to pending and discards work with git reset HEAD + git checkout -- . in repo_path. Without task-id, resets all tasks in the project. Also clears the checkpoint cursor.

$ squire reset orchestrator-dashboard task-005
  ✓ task-005 → pending  (Add commit log empty state)

1 task(s) resetada(s).
  ✓ checkpoint cursor resetado
⚠ Limpando git state em /home/ai-debian/projects/orchestrator-dashboard
✓ git checkout -- . OK

Warning

reset discards uncommitted changes in the project's working tree. Squire auto-commits after every approved task, so usually only the current task's work is lost — but confirm with git status in the repo before.

Tasks

Subcommands delegated to tasks_cli.py. For the Task model and tasks.json shape, see Tasks.

`squire tasks list <project>`

Lists tasks with visual status. Shortcut: squire tasks <project> (no subcommand).

$ squire tasks orchestrator-dashboard
  ✓ [task-001] Setup Next.js scaffolding
  ✓ [task-002] Add fixture data loaders
  ⟳ [task-003] Implement ProjectCard component
  · [task-004] Implement Timeline component
  · [task-005] Implement AlertBanner component
  ...

Legend: ✓ completed · ⟳ implementing · ⌛ homologating · · pending · ✗ blocked.

`squire tasks add <project>`

Adds a task interactively or via flags.

Flag	Description
`--title "..."`	Required title
`--desc "..."`	Description (otherwise, opens `$EDITOR`)
`--id "..."`	Custom ID (default: next free `task-NNN`)
`--skip-homolog`	Auto-approve after inner loop (no Claude call)
`--max N`	`max_attempts` (default: 10)
`--max-homolog N`	`max_homologation_attempts` (default: 5)

`squire tasks edit <project> [task-id]`

Opens the task in $EDITOR (editable YAML format). Without task-id, opens the entire tasks.json.

`squire tasks rm <project> <task-id>`

Removes the task. No double-confirm — this only touches state JSON, easy to recover from backup or git.

`squire tasks split <project> <task-id>`

Asks Claude to subdivide the task into subtasks. Shows the proposal and allows one refinement before applying.

`squire tasks plan <project> [--desc "..."]`

Asks Claude to generate an initial task list from a free-form description. Up to 3 interactive refinement cycles. At the end, asks whether to replace or append to the current tasks.json.

$ squire tasks plan orchestrator-dashboard --desc "Next.js page reading JSON state"
[planning] Claude gerando rascunho...
[planning] 11 tasks propostas. Refinar? [y/N] n
[planning] Modo: (s)ubstituir / (a)nexar / (c)ancelar? s
✓ 11 tasks gravadas em tasks.json

Project

`squire new <project>`

Creates a new project with template project.json + tasks.json in STATE_ROOT/projects/<project>/.

Flag	Default
`--repo <path>`	`/home/ai-debian/projects/<project>`
`--name <name>`	`<project>` (same as the ID)
`--stack <csv>`	`typescript`
`--backend <name>`	`opencode` (also accepts `litellm`, `crush`)

$ squire new my-api --repo /home/ai-debian/projects/my-api \
              --stack python,fastapi --backend opencode
✓ Projeto 'my-api' criado em /home/ai-debian/squire-state/projects/my-api
...

`squire projects`

Lists available projects (basenames of directories in STATE_ROOT/projects/).

`squire rm <project>`

Removes the project's state after double confirmation: you must type <project> <NATO-word> (e.g., my-api echo) to confirm. The repo_path (code on disk) is NOT touched.

$ squire rm my-api
⚠  Remoção de projeto: my-api
   Diretório de estado: /home/ai-debian/squire-state/projects/my-api
   ...
Para confirmar, digite exatamente: my-api echo

> my-api echo
✓ Projeto 'my-api' removido.

Insight: using a NATO alphabet word (alpha, bravo, charlie, ... zulu) prevents accidental rm from clipboard or shell history — you have to read the prompt to know which word to type. See squire.py:1087.

Budget

Commands related to cost tracking and USD caps. Details in Cost and Budget.

`squire budget` (or `squire budget show`)

Shows today's spend + configured cap + per-model breakdown.

$ squire budget
=== Budget — 2026-05-11 (UTC) ===

  Spent hoje:   $1.247  (24,381 tokens)
  Daily cap:    $10.00  (12% usado)
  Restante:     $8.753
  Per-task cap: $2.00

  Por modelo:
    claude-opus-4-7: $1.247
    journal-synth: $0.000

Para configurar:
  squire budget set --daily 10 --per-task 2

`squire budget set --daily X --per-task Y`

Persists USD caps in $SQUIRE_STATE_ROOT/budget.json. Env vars (SQUIRE_DAILY_USD_BUDGET, SQUIRE_PER_TASK_USD_CAP) take precedence over the file.

`squire budget reset`

Zeros the daily counters (global-stats.json). Useful when you want to restart counting without waiting for UTC rollover.

Help

`squire help`

Prints the summary of all commands. Aliases: squire -h, squire --help, and squire (no arguments).

Appendix — CLI environment variables

Variable	Default	Description
`SQUIRE_STATE_ROOT`	`/home/ai-debian/squire-state`	Persistent state root (used by all commands)
`EDITOR`	`nano`	Editor for `squire tasks edit`

Other env vars (that affect orchestrator behavior, not the CLI itself) are in Configuration.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI

Table of contents

Execution

`squire run <project>`

`squire bg <project>`

`squire resume <project> [bg]`

`squire dry <project>`

Observation

`squire status [<project>]`

`squire log`

Control

`squire kill`

`squire unlock`

Recovery

`squire unblock <project> [task-id …]`

`squire reset <project> [task-id …]`

Tasks

`squire tasks list <project>`

`squire tasks add <project>`

`squire tasks edit <project> [task-id]`

`squire tasks rm <project> <task-id>`

`squire tasks split <project> <task-id>`

`squire tasks plan <project> [--desc "..."]`

Project

`squire new <project>`

`squire projects`

`squire rm <project>`

Budget

`squire budget` (or `squire budget show`)

`squire budget set --daily X --per-task Y`

`squire budget reset`

Help

`squire help`

Appendix — CLI environment variables

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI

Table of contents

Execution

squire run <project>

squire bg <project>

squire resume <project> [bg]

squire dry <project>

Observation

squire status [<project>]

squire log

Control

squire kill

squire unlock

Recovery

squire unblock <project> [task-id …]

squire reset <project> [task-id …]

Tasks

squire tasks list <project>

squire tasks add <project>

squire tasks edit <project> [task-id]

squire tasks rm <project> <task-id>

squire tasks split <project> <task-id>

squire tasks plan <project> [--desc "..."]

Project

squire new <project>

squire projects

squire rm <project>

Budget

squire budget (or squire budget show)

squire budget set --daily X --per-task Y

squire budget reset

Help

squire help

Appendix — CLI environment variables

`squire run <project>`

`squire bg <project>`

`squire resume <project> [bg]`

`squire dry <project>`

`squire status [<project>]`

`squire log`

`squire kill`

`squire unlock`

`squire unblock <project> [task-id …]`

`squire reset <project> [task-id …]`

`squire tasks list <project>`

`squire tasks add <project>`

`squire tasks edit <project> [task-id]`

`squire tasks rm <project> <task-id>`

`squire tasks split <project> <task-id>`

`squire tasks plan <project> [--desc "..."]`

`squire new <project>`

`squire projects`

`squire rm <project>`

`squire budget` (or `squire budget show`)

`squire budget set --daily X --per-task Y`

`squire budget reset`

`squire help`