Verb reference¶

Jetsam commands are organized into workflow verbs (plannable, state-aware operations) and inspection verbs (read-only queries).

Overview¶

Verb	Alias	Description
`status`	`s`	Show repository state snapshot
`save`	`v`	Stage and commit with smart defaults
`sync`	`y`	Fetch, rebase/merge, and push
`ship`	`h`	Full pipeline: stage, commit, push, open PR
`switch`	`w`	Switch branches with automatic stash/unstash
`start`	`b`	Start work on an issue or feature
`finish`	`f`	Merge PR and clean up branch
`tidy`	`t`	Prune merged branches and stale refs
`release`	`r`	Tag, push, and create platform release
`log`	`l`	Condensed commit history
`diff`	`d`	Show diff with smart defaults
`pr`	`p`	Pull request operations
`prs`	—	List PRs with status
`checks`	`c`	CI check status
`issues`	`i`	List issues
`init`	—	Initialize jetsam

Common flags¶

All workflow verbs support:

--dry-run — show plan without executing
--execute — execute without interactive confirmation
--json (global) — output as JSON

Workflow verbs¶

These verbs build plans, show previews, and execute multi-step operations.

status¶

Show repository state snapshot.

jetsam status

Returns: branch, upstream tracking, ahead/behind counts, staged/unstaged/untracked files, stash count, and PR details if available.

  On feature-branch  (↑2, ↓1 vs origin/feature-branch)
  Staged:    src/new.py
  Modified:  src/existing.py
  Untracked: scratch.txt
  PR #42: open  checks: passing

save¶

Stage and commit with smart defaults.

jetsam save [-m MESSAGE] [--include GLOB] [--exclude GLOB] [FILES...]

Arguments:: FILES — Optional explicit file paths to stage.
Options:: -m, --message — Commit message. Auto-generated from file paths if omitted.; --include — Glob pattern to filter which files to stage.; --exclude — Glob pattern to exclude files from staging.

Behavior:

Without FILES or --include, stages modified tracked files (not untracked)
With --include, stages matching files from both unstaged and untracked
Already-staged files are always included in the commit

Examples:

# Stage modified files and commit
jetsam save -m "fix parser bug"

# Stage specific files
jetsam save src/parser.py tests/test_parser.py -m "fix parser"

# Stage only Python files
jetsam save --include "*.py" -m "update code"

# Stage everything except tests
jetsam save --include "*" --exclude "tests/*" -m "update"

sync¶

Fetch from upstream, rebase or merge, and push.

jetsam sync [--strategy rebase|merge]

Options:: --strategy — Sync strategy. Defaults to rebase on feature branches, merge on the default branch.

Behavior:

Stashes dirty changes automatically before syncing, restores after
On feature branches: rebases onto upstream (or origin/<default> if no upstream)
On the default branch: merges from upstream
Pushes after sync if there are local commits

Example:

# Default: rebase on feature, merge on main
jetsam sync

# Force merge strategy
jetsam sync --strategy merge

ship¶

Full pipeline: stage, commit, push, and open a PR.

jetsam ship [-m MESSAGE] [--to BRANCH] [--no-pr] [--merge]
            [--include GLOB] [--exclude GLOB] [FILES...]

Arguments:: FILES — Optional explicit file paths to stage (stages exactly these files).
Options:: -m, --message — Commit message and PR title.; --to — Target branch for PR (default: main/master).; --no-pr — Skip PR creation.; --merge — Also merge the PR after creating it.; --include — Glob pattern for files to stage.; --exclude — Glob pattern to exclude files.

Behavior:

Stages files (same logic as save)
Commits with the provided message
Pushes to the remote (sets upstream if needed)
Creates a new PR, or notes the existing one was updated via push
Optionally merges the PR
If nothing to commit but there are unpushed commits, skips straight to push/PR

Examples:

# Ship everything with a message
jetsam ship -m "add dark mode"

# Ship specific files only
jetsam ship -m "fix parser" src/parser.py tests/test_parser.py

# Ship without creating a PR
jetsam ship -m "update config" --no-pr

# Ship and immediately merge
jetsam ship -m "hotfix" --merge

# Ship to a specific branch
jetsam ship -m "backport" --to release/v2

# Push already-committed changes and open a PR
jetsam ship

switch¶

Switch branches with automatic stash/unstash.

jetsam switch BRANCH [-c/--create]

Arguments:: BRANCH — Target branch to switch to.
Options:: -c, --create — Create the branch if it doesn’t exist.

Behavior:

If the working tree is dirty, automatically stashes changes before switching and pops the stash on the target branch

Example:

jetsam switch main
jetsam switch -c new-feature

start¶

Start work on an issue or feature.

jetsam start TARGET [-w/--worktree] [--base BRANCH] [--prefix PREFIX]

Arguments:: TARGET — Issue number (e.g. 42) or branch name (e.g. fix-parser).
Options:: -w, --worktree — Create a git worktree instead of switching branches.; --base — Base branch to create from (default: main/master).; --prefix — Branch name prefix (e.g. feature/).

Behavior:

If TARGET is numeric, fetches the issue title from GitHub/GitLab and generates a branch name slug (e.g. 42-fix-parser-bug)
If TARGET is a name, uses it directly as the branch name
In worktree mode, creates a new worktree in .worktrees/<branch>
In branch mode, stashes dirty changes before switching

Examples:

# Start from issue number (fetches title for branch name)
jetsam start 42

# Start with explicit branch name
jetsam start fix-parser

# Start in a worktree for parallel work
jetsam start 42 --worktree

# Use a branch prefix
jetsam start fix-it --prefix feature/

finish¶

Merge PR and clean up the current branch.

jetsam finish [--strategy squash|merge|rebase] [--no-delete]

Options:: --strategy — Merge strategy (default: squash).; --no-delete — Keep the branch after merging.

Behavior:

Merges the PR for the current branch (if one exists)
Switches back to the default branch (or removes the worktree if in one)
Fetches to update refs
Deletes the feature branch (unless --no-delete)

Example:

jetsam finish
jetsam finish --strategy rebase --no-delete

tidy¶

Clean up merged branches and stale remote refs.

jetsam tidy

Behavior:

Prunes remote-tracking branches that no longer exist on the server
Deletes local branches whose upstream is gone (merged and deleted remotely)
Prunes stale worktree references (if worktrees are in use)

release¶

Tag, push the tag, and create a platform release.

jetsam release TAG [--title TITLE] [--notes NOTES] [--draft]

Arguments:: TAG — Tag name (e.g. v0.1.0).
Options:: --title — Release title (defaults to tag name).; --notes — Release notes text.; --draft — Create as a draft release.

Behavior:

Creates an annotated git tag (skipped if tag already exists)
Pushes the tag to the remote
Creates a GitHub/GitLab release
Warns if the working tree is dirty or not on the default branch

Examples:

jetsam release v0.1.0
jetsam release v0.2.0 --title "Version 0.2.0" --notes "Bug fixes and improvements"
jetsam release v1.0.0-rc1 --draft

Inspection verbs¶

These verbs are read-only and do not create plans.

log¶

Show condensed commit history.

jetsam log [-n COUNT] [--branch BRANCH]

Options:: -n, --count — Number of commits to show (default: 10).; --branch — Branch to show log for (default: current).

diff¶

Show diff with smart defaults.

jetsam diff [--target REF] [--stat] [--staged]

Options:: --target — Diff target ref (default: working tree changes).; --stat — Show only stat summary.; --staged — Show staged changes instead of unstaged.

pr¶

Pull request operations.

# View PR for current branch
jetsam pr

# Create a new PR
jetsam pr create [-t TITLE] [-b BODY] [--base BRANCH] [--draft]

# List PRs
jetsam pr list [--state open|closed|merged|all] [--author USER]

prs¶

List pull requests with check and review status.

jetsam prs [--state open|closed|merged|all] [--author USER]

checks¶

Show CI check status for the current branch or a specific PR.

jetsam checks [--pr NUMBER]

issues¶

List issues from the project’s issue tracker.

jetsam issues [--state open|closed|all] [--label LABEL]

Setup verbs¶

init¶

Initialize jetsam in the current repository.

jetsam init [--mcp] [--aliases] [--agents TARGET] [--hooks TARGET]

Options:: --mcp — Add jetsam MCP server entry to .mcp.json (merges with existing file).; --aliases — Install shell aliases to your shell config.; --agents TARGET — Generate agent instructions file with JetSam routing table. Values: claude (CLAUDE.md), gemini (GEMINI.md), agents (AGENTS.md), none (skip), or a custom file path.; --hooks TARGET — Generate agent hook config for soft enforcement. Values: claude (Claude Code PreToolUse hooks), none (skip).

Examples:

# Full agent setup
jetsam init --mcp --agents claude --hooks claude

# MCP only (existing behavior)
jetsam init --mcp

# Agent instructions for a different framework
jetsam init --agents gemini

See Getting started for details.