Installation

# Package manager
bun add -g schub@latest

Test A Local Built Package (No Publish)

From the monorepo root:

# 1) Build the CLI + bundled dashboard + bundled API
bun run --cwd packages/schub build:bundle

# 2) Run the built package entrypoint
#    (set explicit local paths so the run is isolated/reproducible)
SCHUB_DB_PATH=/tmp/schub-local.db \
SCHUB_STORAGE_PATH=/tmp/schub-local-storage \
node packages/schub/dist/index.js dashboard

From another project/repo, you can run the exact same built package via absolute path:

SCHUB_DB_PATH=/tmp/schub-local.db \
SCHUB_STORAGE_PATH=/tmp/schub-local-storage \
node /absolute/path/to/schub/packages/schub/dist/index.js dashboard

Usage

Run the CLI using schub.

schub [command]

If no command is provided, the TUI dashboard will launch. Use schub dashboard to start the web dashboard (dev server from source, preview from built).

Environment

• SCHUB_API_PORT - Overrides the API port when schub auto-starts the API (maps to the API PORT).
• SCHUB_DASHBOARD_PORT - Overrides the dashboard port for schub dashboard (dev or preview).
• SCHUB_DB_PATH - Path to the local SQLite database used by schub services (default: ~/.schub/schub.db).
• SCHUB_STORAGE_PATH - Filesystem root used for file uploads and attachments (default: ~/.schub/storage).

Project-scoped DB commands use the project id from .schub/config.json.

Commands

Init

• schub init --project-id <project-id> - Validate the project id in services and write .schub/config.json at the current git root (repo root or current git worktree root).

Proposals

• schub proposals write - Write a new proposal locally from the template (allocates a DB shorthand but does not upload).
• schub proposals create - Create a proposal directly in the database with --content (programmatic/API use).
• schub proposals save - Save all files in one proposal folder to DB/storage (--id) or save all local proposals (--all).
• schub proposals pull - Pull a proposal from the database into the local .schub folder (requires local .schub/config.json).
• schub proposals update - Update a proposal status in frontmatter and sync to DB.
• schub proposals list - List proposals (--show-all includes archived/rejected).
• schub proposals files - List local and DB files for a proposal (--id).
• schub proposals archive - Archive a proposal (use --skip-tickets to keep tickets active).
• schub proposals delete - Delete a proposal and clear linked tickets.

Proposal IDs

Proposal ids are stored as P####_<slug>. Any command that accepts proposal ids via --id also accepts the shorthand P#### when it uniquely matches a proposal directory under .schub/proposals or .schub/archive/proposals.

schub proposals save --id P0003
schub proposals save --all
schub proposals pull --id P0003

Docs

• schub docs init - Scaffold .schub/docs/docs.json and starter markdown (index.md).
• schub docs init --overwrite - Replace starter docs files when they already exist.
• schub docs save - Save .schub/docs/docs.json and **/*.md to persisted project docs storage.
• schub docs pull - Pull persisted project docs back into local .schub/docs (requires local .schub/config.json).

Dashboard

• schub dashboard - Start the web dashboard (dev opens http://localhost:5173, preview opens http://localhost:4173).
• schub tui - Launch the TUI dashboard.

Ticket Management

• schub tickets write - Write a new ticket locally from the template (allocates a DB shorthand but does not upload).
• schub tickets create - Create a ticket directly in the database with --content (programmatic/API use).
• schub tickets list - List all tickets in the current project context.
• schub tickets check - Toggle a checklist item in a ticket.
• schub tickets update - Move backlog tickets to any ticket status configured for the project in DB.
• schub tickets implement - Move a ticket to wip and launch Opencode.
• schub tickets save - Validate and save one ticket (--id) or all local tickets (--all) to DB/storage.
• schub tickets pull - Pull tickets from the database into the local .schub/tickets folder (requires local .schub/config.json).
• schub tickets refine - Refine a ticket using an LLM prompt (--id).
• schub tickets files - List local and DB files for a ticket (--id).
• schub tickets swap --id <ticket> [--attempt <attempt>] - Swap the repo to a ticket attempt's worktree state.
• schub tickets swap --back - Restore the original repo state after a swap.
• schub tickets swap --status - Show current swap state.
• schub tickets merge --id <ticket> [--attempt <attempt>] - Squash-merge a ticket attempt into the current branch.

Ticket implementation

schub tickets implement --id T0007
schub tickets implement --id T0007 --mode worktree --project-id <project-id>

• --mode defaults to none (no worktree).
• --mode worktree creates ~/.schub/worktrees/<project-id>/<ticket-shorthand>/<attempt-shorthand> and requires --project-id.
• --mode none runs from the current repo without a worktree.
• --worktree-root overrides the default ~/.schub/worktrees location.

Ticket checklist updates

schub tickets check --id T0007 --item 2

Ticket status updates

schub tickets update --id T0004 --id T0005 --status reviewed

• --id (repeatable) selects backlog ticket IDs to move.
• --status sets the target status and must match a project ticket status in DB.

Swap, merge, and worktree cleanup

# Preview an agent's work
schub tickets swap --id TK0084 --attempt A0022

# Return to your original branch
schub tickets swap --back

# Squash-merge an attempt into the current branch
schub tickets merge --id TK0084 --attempt A0022

# Remove the attempt's worktree after merging
schub worktree delete --ticket-id TK0084 --attempt A0022

Overview view shortcut

In Overview view, press s on a selected backlog or reviewed ticket to open the status modal. For backlog tickets choose Reviewed or Archive. For reviewed tickets choose Backlog or Archive, then press enter to confirm or esc to cancel.

Worktree

• schub worktree delete --ticket-id <ticket> [--attempt <attempt>] - Remove a ticket attempt's worktree from disk and git tracking.

Setup

• schub setup --agent <agent> - Install all skill templates for a coding agent. Supported agents: opencode, claude, codex.

schub setup --agent opencode --agent claude --agent codex

Install paths per agent:

• opencode → ~/.opencode/skills/<name>/SKILL.md
• claude → ~/.claude/skills/<name>.md
• codex → ~/.codex/skills/<name>.md

Templates & Reviews

• schub templates create --name adr - Create a new Architectural Decision Record file.
• schub templates create --name cookbook - Create a new cookbook file.
• schub templates create --name review - Create a REVIEW_ME.md file.
• schub templates list - List all templates in the database.
• schub templates save - Save local .schub/templates/*.md files to the database (--name for one, or all).
• schub templates pull - Pull templates from the database to local .schub/templates/ (--name for one, or all).
• schub review complete - Finalize a review, converting questions into a Q&A section.

LLM Skills

• create-proposal - Scaffold and update proposals, including review requirements.
• create-ticket - Create a ticket for any requested repo change.
• create-sub-tickets - Generate actionable child ticket files under .schub/tickets/ from a parent ticket id.
• implement-ticket - Implement a single ticket end-to-end and move it across ticket status folders.
• review-proposal - Run a proposal review session with open questions and Q&A updates.
• refine-ticket - Refine an existing ticket into the ticket template.

LLM Workflow

LLMs should write locally, then update/save:

1. proposals write / tickets write — scaffold a local file from a template
2. Edit the local file with concrete details
3. proposals update / tickets update — update status (syncs to DB)
4. proposals save / tickets save — persist all local files to DB storage

Contributing

This CLI is built using Ink for the interactive UI and Bun for execution.

Scripts

• bun run schub: Run the CLI in development mode.
• bun run schub:built: Run the built CLI from dist/ (run bun run build first).
• bun run build: Build the CLI to dist/.
• bun run lint: Lint the codebase.
• bun run format: Format the codebase.
• bun run test: Run tests.