CLI & Worktrees

Core commands

Command	Use
roscoe	Open the home TUI.
roscoe --help	List the supported subcommands and flags.
roscoe onboard /path/to/project	Create or refresh the project contract.
roscoe start codex@/path/to/project	Start a monitored lane on the main repo.
roscoe start codex@/path/to/project:auth-refactor	Start a lane in a named worktree.
roscoe projects	List remembered projects and discovered worktrees.
roscoe worktrees /path/to/project	List the main repo and named worktrees.
roscoe worktree-remove /path/to/project auth-refactor	Delete a completed or abandoned worktree.
roscoe profiles	List detected provider and auth profiles.

Start spec formats

Format	Example	Meaning
profile	codex	Uses the current working directory as the project root.
profile@dir	codex@/path/to/project	Starts a lane against an onboarded project directory.
profile@dir:task	codex@/path/to/project:auth-refactor	Creates or reuses a task worktree before launch.

When to prefer the CLI

Use the direct command surface when:

• you are scripting Roscoe from the shell
• you want to start a specific lane without entering the home TUI first
• you need to inspect or clean up worktrees non-interactively
• you want to confirm profile visibility quickly with roscoe profiles

When to prefer the TUI

Use the TUI for:

• normal day-to-day operation
• lane review and draft control
• preview breaks
• project retuning from runtime controls
• SMS configuration and test sends