basecamp-cli

Basecamp CLI

basecamp is the official command-line interface for Basecamp. Manage projects, todos, messages, and more from your terminal or through AI agents.

• Works standalone or with any AI agent (Claude, Codex, Copilot, Gemini)
• JSON output with breadcrumbs for easy navigation
• OAuth authentication with automatic token refresh
• Includes agent skills plus native Claude Code and Codex plugins

Quick Start

macOS / Linux / WSL2

curl -fsSL https://basecamp.com/install-cli | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/basecamp/basecamp-cli/main/scripts/install.ps1 | iex

On Windows 11 with Smart App Control, see Troubleshooting if the install is blocked.

That's it. You now have full access to Basecamp from your terminal.

brew install --cask basecamp/tap/basecamp-cli

yay -S basecamp-cli

# Download from https://github.com/basecamp/basecamp-cli/releases/latest
sudo apt install ./basecamp-cli_*_linux_amd64.deb            # Debian/Ubuntu
sudo dnf install ./basecamp-cli_*_linux_amd64.rpm            # Fedora/RHEL
sudo apk add --allow-untrusted ./basecamp-cli_*_linux_amd64.apk  # Alpine

scoop bucket add basecamp https://github.com/basecamp/homebrew-tap
scoop install basecamp-cli

curl -fsSL https://raw.githubusercontent.com/basecamp/basecamp-cli/main/scripts/install.sh | bash

nix profile install github:basecamp/basecamp-cli

go install github.com/basecamp/basecamp-cli/cmd/basecamp@latest

Usage

basecamp projects list                            # List projects
basecamp todos list --in 12345                    # Todos in a project
basecamp todos create "Fix bug" --in 12345        # Create todo
basecamp todos complete 67890                     # Complete todo
basecamp cards done 67890 --in 12345              # Complete card (move to Done)
basecamp search "authentication"                  # Search across projects
basecamp files list --in 12345                    # List docs & files
basecamp cards list --in 12345                    # List cards (Kanban)
basecamp chat post "Hello" --in 12345             # Post to chat
basecamp comments create 67890 "@Jane.Smith, done!"    # Comment with @mention

Output Formats

basecamp projects              # Styled output in terminal, JSON when piped
basecamp projects --json       # JSON with envelope and breadcrumbs
basecamp projects --quiet      # Raw JSON data only

JSON Envelope

Every command supports --json for structured output:

{
  "ok": true,
  "data": [...],
  "summary": "5 projects",
  "breadcrumbs": [{"action": "show", "cmd": "basecamp projects show <id>"}]
}

Breadcrumbs suggest next commands, making it easy for humans and agents to navigate.

Authentication

OAuth 2.1 with automatic token refresh. First login opens your browser. When the server advertises the OAuth device flow, login uses it automatically: you approve a short code in the browser instead of a redirect. Login falls back to Launchpad's authorization-code flow only when no modern OAuth issuer is advertised for the server; once a modern issuer is selected, login failures surface loudly rather than silently falling back.

basecamp auth login              # Authenticate with Basecamp
basecamp auth login --scope read # Read-only access (default; ignored by Launchpad)
basecamp auth login --scope full # Full read+write access (ignored by Launchpad)
basecamp auth token              # Print token for scripts

Multiple Identities

Use named profiles when the same machine or agent gateway needs more than one Basecamp identity. Each profile has its own stored OAuth credentials and can be selected per command:

basecamp profile create design-agent
basecamp profile create ops-agent
basecamp --profile design-agent todo "Fix bug" --in 12345 --list 67890

Set a default with basecamp profile set-default <name>, or set BASECAMP_PROFILE=<name> for a process. Actions are posted as the authenticated user for the selected profile.

Custom OAuth Credentials

To use your own OAuth app (e.g., a custom Launchpad integration):

Both BASECAMP_OAUTH_CLIENT_ID and BASECAMP_OAUTH_CLIENT_SECRET must be set together.

AI Agent Integration

basecamp works with any AI agent that can run shell commands.

Both plugins require the basecamp CLI installed and on your PATH.

Claude Code: basecamp setup claude — installs the plugin with skills and agent workflow support.

Codex: basecamp setup codex — registers the 37signals marketplace and installs the native plugin with Basecamp skills and diagnostics. Start a new Codex thread afterward to load the skills.

Manual Codex installation uses the same marketplace:

codex plugin marketplace add basecamp/claude-plugins
codex plugin add basecamp@37signals

To pick up a newer plugin version later, refresh the marketplace with codex plugin marketplace upgrade 37signals (or re-run basecamp setup codex).

Other agents: Point your agent at skills/basecamp/SKILL.md for Basecamp workflow coverage.

Agent discovery: Every command supports --help --agent for structured JSON output (flags, gotchas, subcommands). Use basecamp commands --json for the full catalog.

See install.md for step-by-step setup instructions.

Configuration

~/.config/basecamp/           # Your Basecamp identity
├── credentials.json          #   OAuth tokens (fallback when keyring unavailable)
└── config.json               #   Global preferences

~/.config/basecamp/theme/     # Tool display (optional)
└── colors.toml               #   TUI color scheme

~/.cache/basecamp/            # Ephemeral tool data
├── completion.json           #   Tab completion cache
└── resilience/               #   Circuit breaker state

.basecamp/                    # Per-repo (committed to git)
└── config.json               #   Project, account defaults

A leftover ~/.config/basecamp/client.json (from the removed development client-registration flow) is obsolete and safe to delete.

Troubleshooting

basecamp doctor              # Check CLI health and diagnose issues
basecamp doctor --verbose    # Verbose output with details
basecamp doctor --json       # Structured checks, including Claude and Codex

Windows: Smart App Control and SmartScreen

Releases up to v0.8.0-rc.1 ship an unsigned basecamp.exe. To check whether your installed binary is signed:

Get-AuthenticodeSignature (Get-Command basecamp).Source

Smart App Control (Windows 11) blocks unsigned executables no matter where they were downloaded from, and it has no per-app exceptions — this applies to the PowerShell installer, Scoop installs, and manual downloads alike. If it blocks an unsigned basecamp.exe, two options:

1. Use WSL2 (preferred). Install the Linux build inside WSL2 — Smart App Control doesn't apply there and your Windows security setup is untouched: wsl --install, then inside the WSL terminal: curl -fsSL https://basecamp.com/install-cli | bash
2. Turn Smart App Control off (Windows Security → App & browser control → Smart App Control settings) and leave it off while using the unsigned build. Because there are no per-app exceptions, turning it back on re-blocks basecamp.exe on its next run — only re-enable after upgrading to a signed build. Windows 11 with the March/April 2026 updates can re-enable Smart App Control from Windows Security without a reset; on older builds re-enabling requires resetting Windows, so prefer WSL2 there.

SmartScreen (without Smart App Control) may warn on first run of an unrecognized executable — choose "More info" → "Run anyway" if you downloaded the release from this repository.

Development

make build            # Build binary
make test             # Run Go tests
make test-e2e         # Run e2e tests
make lint             # Run linter
make check            # All checks (fmt-check, vet, lint, test, test-e2e)

See CONTRIBUTING.md for development setup.

License

MIT