Sync your Hamster Briefs, Tasks, and skills into the repository your AI coding tools work in, and run Delivery commands from the terminal.
The Hamster CLI is a single Go binary that turns your Hamster workspace into local markdown your AI coding tools can read directly. In a repository, it writes a .hamster/ projection, reusing the nearest existing one or creating one at the repository root, and keeps ~/.hamster/ as the user-level cache. A one-shot sync for a Brief UUID, slug, or full Hamster URL syncs only that Brief.
The Hamster plugin setup skill installs the CLI if it's missing. This command is for a terminal or CI without a plugin.
curl -fsSL https://tryhamster.com/cli/install | bashEach project-context sync also generates .claude/skills/hamster-project-context/SKILL.md under the selected base for Claude Code. This context skill does not install the Hamster plugin or create Ask and Ship. Separately, hamster skills sync maintains shared workspace skills under .agents/skills/ and can link them into agent-specific skill directories.
The CLI is a sync engine, not an editor. Editing Briefs, Tasks, and skills happens in Hamster (or, for skills, optionally in your repo with bidirectional sync). Supported CLI write commands let agents update task status and create subtasks from the terminal. The CLI's job is to make that content available to your coding tools. Use it to pull live content before Delivery, update Task status in bulk, create Briefs from your build pipeline, or ask your coding agent for the next unblocked Task and Initiative health against the same live workspace your team sees in Hamster.
The CLI and MCP Server overlap, but neither replaces the other: most MCP tools have a CLI command, and Available Tools lists the few that are MCP-only. In the Hamster plugin, Ask calls the hosted MCP Server and Ship drives the CLI. The CLI owns local-only workflows such as sync, terminal chat, and the TUI.
.hamster/ projection you are in, or pull one Brief by UUID, slug, or URL| Command | What it does |
|---|---|
hamster auth login | Browser sign-in; stores your session in your OS keychain |
hamster init | Create the repository's .hamster/ projection, pick a team, and run the first sync |
hamster sync [identifier] | Refresh the .hamster/ projection you are in, or pass a Brief UUID, slug, or full Hamster URL to sync only that Brief |
hamster sync --watch | Keep the .hamster/ projection current; Brief-scoped sync does not support watch mode |
hamster team list, hamster team switch, hamster team members | List teams, select the active team, or inspect its members |
hamster brief create --title "Title" | Create a Brief from the terminal |
hamster brief plan <id-or-slug> --generate | Start Plan generation for a Brief |
hamster brief deliver <id-or-slug> | Start Delivery for a Brief |
hamster task status <id> <status> | Move a Task to a new status |
hamster brief update <id-or-slug> --owner <user-uuid> | Update brief ownership to a specific user |
hamster goal list --status archived | List archived goals; without this filter, the command lists non-archived goals |
hamster initiative list | List active, non-archived initiatives |
hamster initiative archive <id> | Archive an initiative so it no longer appears in initiative list |
hamster note list --include-archived | List Notes, including archived ones; without a filter, the command lists non-archived notes |
hamster note update <id> --archive | Archive a Note, or change its title, description, or body |
hamster search <query> | Search Briefs, Notes, Initiatives, Goals, Documents, and Tasks by name |
hamster skills sync | Bidirectional skill sync — pull updates and push local edits |
hamster skills agents | Pick which AI agents (Claude Code, Continue, Windsurf, …) get symlinks to .agents/skills/ |
hamster chat "<request>" | Ask Hamster a question or take a workspace action from the terminal |
Run hamster --help for the full command tree. Most commands pair with an MCP Server tool, so you can use them in scripts and automation the same way an agent would call MCP.
Use hamster chat to ask questions and take supported workspace actions without leaving the shell. Use --continue when the next request depends on the previous answer.
Responses render Markdown, and workspace references open as clickable links.
hamster chat "List the Briefs assigned to me and show which are approved."
hamster chat --continue "Generate a Plan for each Brief that is missing one. Do not overwrite existing Plans."
When asked to generate missing Plans, Hamster creates each missing Plan and leaves existing Plans unchanged.
Use hamster note to list, read, create, and update Notes:
hamster note list — Lists non-archived notes. --search matches the title and description without case sensitivity, and --owner <user-uuid> or --assigned-to-me filter by assignee. --archived lists only archived notes, and --include-archived lists both. Page through results with --limit (default 50, max 200) and --offset.hamster note get <id> — Shows the note's title and description. Add --content to print the body as markdown.hamster note create --title "Title" — Creates a note. Add --description and --content to fill it in.hamster note update <id> — Changes only the fields you pass: --title, --description, --content, or --archive. --content replaces the body, and an empty value clears it. --archive=false unarchives the note.Pass - to --content to read the body from stdin:
hamster note update <id> --title "New title"
echo "## Replaced body" | hamster note update <id> --content -
hamster note update <id> --archive
The CLI keeps your shared agent skills in sync between your repo and your workspace. hamster skills sync runs in both directions by default:
[K]eep local / [U]se remote / [S]kip prompt before anything is overwritten.If your IDE or agent expects skills under its own path (.claude/skills, .continue/skills, .windsurf/skills, etc.) instead of the universal .agents/skills/, run hamster skills agents to pick which directories should symlink to the canonical location. Hamster maintains symlinks safely — it never deletes the canonical data even if an agent directory was previously a symlink.
hamster skills sync --pull-only and --push-only flags are available when you want to scope the sync to one direction.
Ask and Ship come from the Hamster plugin, not from hamster sync. Ask falls back to hamster chat when the hosted MCP Server is unavailable and the CLI is installed and signed in, and Ship works from the synced .hamster/ context. See Plugin Skills for how to start them and what they accept.
The same binary works in two contexts:
HAMSTER_ACCOUNT_ID and authenticate with an access token environment variable to skip every prompt.Auth credentials live in your OS keychain by default (macOS Keychain, Windows Credential Manager, or the Linux Secret Service). On WSL or headless setups without a keychain, the CLI stores them in ~/.hamster/auth.json, protected by user-only directory and file permissions.
tryhamster.com/... URL straight into hamster sync — the CLI parses all three, syncs only that Brief, and reuses the nearest existing projection..hamster/ and .claude/skills/hamster-project-context/ are git-ignored by default — each carries its own .gitignore, because they are generated and account-specific. Delete that .gitignore if your team wants the synced markdown tracked in git.hamster sync --watch in a side terminal during a session — your AI agent always sees the latest Brief and Task state without you needing to remember to re-sync.