Skip to content

install.md

Latest commit

 

History

History
291 lines (211 loc) · 12.3 KB

install.md

File metadata and controls

291 lines (211 loc) · 12.3 KB
Raw

Basecamp CLI Installation Guide

Install the Basecamp CLI and connect it to your AI agent. Execute all steps autonomously.

On an interactive terminal, the installer runs the recommended setup after download: browser authentication, the OAuth-bound account (otherwise the existing configured account or first available account) saved globally, the global project default cleared, and every detected coding agent connected. Directory-specific and environment project settings continue to apply. Use basecamp setup --customize when you want to choose those settings. Without a usable controlling terminal, the installer installs the baseline agent skill and, on a best-effort basis, attempts to connect a single detected coding agent.

DONE WHEN: basecamp --version && basecamp auth status both succeed.

TODO

  • Install Basecamp CLI
  • Authenticate with Basecamp
  • Connect agent (optional — the piped installer already attempts one detected agent)

Step 1: Install Basecamp CLI

Run the matching command for your environment:

macOS / Linux / WSL2 / Git Bash

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

Windows PowerShell

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

Note: The install scripts run basecamp setup whenever they can attach it to a usable interactive terminal, including the standard curl | bash command. When no usable controlling terminal is available, output is redirected, or BASECAMP_NONINTERACTIVE=1/true is set, they skip authentication and run basecamp setup agents. That command installs the baseline agent skill and attempts to connect a single detected coding agent (best effort). If several agents are detected, or none is, only the baseline skill is installed and the per-agent commands are surfaced. Explicitly skipping first-time setup with BASECAMP_SKIP_SETUP=1 still runs setup agents. If optional first-time setup is cancelled or does not finish, the installed CLI remains ready and the installer prints the command to resume setup.

Choose which agent to connect with BASECAMP_SETUP_AGENT (claude, codex, grok, all, or none). Set it for the interpreter, not the fetch:

  • Bash: curl -fsSL https://basecamp.com/install-cli | BASECAMP_SETUP_AGENT=codex bash
  • PowerShell: $env:BASECAMP_SETUP_AGENT='codex'; irm https://raw.githubusercontent.com/basecamp/basecamp-cli/main/scripts/install.ps1 | iex

Windows note: if curl fails with a schannel / CRYPT_E_NO_REVOCATION_CHECK TLS error, prefer the PowerShell installer, Scoop, or Git Bash's /usr/bin/curl instead of the system curl.exe.

Windows 11 with Smart App Control: releases up to v0.8.0-rc.1 ship an unsigned basecamp.exe, which Smart App Control blocks. Prefer WSL2 — run curl -fsSL https://basecamp.com/install-cli | bash inside a WSL terminal — or see Troubleshooting below.

Alternatively install manually:

Option A: Homebrew (macOS/Linux) — Recommended

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

Option B: PowerShell (Windows)

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

Option C: Scoop (Windows)

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

Option D: Linux package (Debian/Ubuntu, Fedora/RHEL, Alpine)

# Download the matching package 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

Arm64: substitute arm64 for amd64 in the filename. Verify the SHA-256 checksum from checksums.txt before installing unsigned Alpine packages.

Option E: Nix

nix profile install github:basecamp/basecamp-cli

Option F: Go install

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

Option G: mise

mise use --global github:basecamp/basecamp-cli@latest

Option H: GitHub Release

Download the archive for your platform from Releases, extract, and move basecamp to a directory on your PATH.

Verify:

basecamp --version
# Expected: basecamp version X.Y.Z

If basecamp: command not found, add it to PATH:

export PATH="$HOME/.local/bin:$PATH"   # macOS / Linux / WSL
export PATH="$HOME/bin:$PATH"          # Git Bash / Windows bash environments
# or for go install:
export PATH="$HOME/go/bin:$PATH"

Upgrading later

Run basecamp upgrade. Installer-script installs upgrade in place (Sigstore-verified download, transactional executable swap, post-upgrade version confirmation). Homebrew and Scoop installs delegate to their package manager, then verify the installed binary reports the new version. System packages (apt/dnf/apk, AUR, Nix), mise, and go install builds are never touched — the command exits nonzero with upgrade guidance for that install method instead. Treat any nonzero exit as not upgraded and follow the hint in the error (upgrade_required, upgrade_incomplete, upgrade_unverified, or upgrade_failed).

Step 2: Authenticate

Interactive installs authenticate during Step 1. If setup was skipped, did not finish, or the installer had no usable terminal, run:

basecamp auth login

This opens browser OAuth. Grant access when prompted.

Verify:

basecamp auth status
# Expected: a line starting "Logged in to https://3.basecampapi.com" (your email and user id follow when known)

EXECUTE NOW: Start with Step 1. Mark TODO items complete as you go. Stop when basecamp --version && basecamp auth status both succeed.

Optional: Connect Your Agent

Do not execute this section unless explicitly requested. The core installation is complete when DONE WHEN passes.

Interactive setup in Step 1 connects every detected agent. Without a controlling terminal, the installer still installs the baseline skill and attempts to connect one detected agent. Run the commands here to force a specific agent, repair a connection, or connect agents that were not available during installation. Every integration requires the basecamp CLI installed above — the plugins and the skill invoke it for every Basecamp operation.

Claude Code

basecamp setup claude

This registers the marketplace and installs the basecamp-cli@37signals plugin with skills, hooks, and agent workflow support.

The plugin was named basecamp until that name was set aside for the hosted Basecamp connector plugin. During a deprecation window basecamp@37signals remains an alias that keeps working; re-running basecamp setup claude replaces it with basecamp-cli@37signals at the same scopes, and basecamp setup codex adds basecamp-cli@37signals and then removes the old ID (Codex installs have no scopes to preserve).

The hooks call the CLI's agent-hook command, so they need a basecamp new enough to have it. If hook errors appear after installing or refreshing the plugin, run basecamp upgrade and start a new session; basecamp agent-hook --help replying "unknown command" confirms the CLI is the old one.

Codex

basecamp setup codex

This installs the shared Basecamp skill, registers the 37signals Codex marketplace, and installs the native plugin. After setup, review and trust the plugin's commit-reference hooks with /hooks (Codex lists untrusted hooks but does not run them until trusted), then start a new Codex thread to load the skills and hooks. The plugin does not inject Basecamp context at session start; Codex selects the skill when a request is relevant or explicitly references Basecamp.

For a manual install:

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

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

Grok Build

basecamp setup grok

This installs the shared Basecamp skill and confirms it is healthy. There is no Grok plugin: Grok reads user skills from ~/.grok/skills/ and from the cross-agent ~/.agents/skills/, so the shared skill at ~/.agents/skills/basecamp/SKILL.md is the whole integration. Setup requires Grok to be present — $GROK_HOME (default ~/.grok) or a grok binary on PATH, in ~/.local/bin, or in $GROK_HOME/bin — and never creates the Grok home itself. Start a new Grok session afterwards to load the skill.

Verify any agent integration with structured diagnostics:

basecamp doctor --json

Other Agents

Point your agent at the skill file for full Basecamp workflow coverage:

skills/basecamp/SKILL.md

Every command supports --help --agent for structured JSON discovery.

Quick Test

basecamp projects --json
basecamp search "meeting" --json

Troubleshooting

Check what you are fixing first. basecamp auth status --json reports oauth_type, and agent means the profile is a Basecamp agent: a principal with no person behind it, which authenticates with its OAuth client rather than a sign-in. None of the logins below apply to one — they would store a person's credential over it — and auth logout would throw away the client credentials it needs to recover. An agent re-authenticates with its own login, which replaces the credential in place. When oauth_type is absent, run whatever the status output's own hint names rather than choosing from the list below:

op read "op://<vault>/<item>/credential" | basecamp auth login --with-client-credentials --client-id <id> -P <profile> --account <id>

Not authenticated:

basecamp auth login

Wrong account:

cat ~/.config/basecamp/config.json
basecamp auth logout && basecamp auth login

Permission denied (read-only, BC3 OAuth only):

basecamp auth login --scope full

Windows 11: Smart App Control blocks basecamp.exe:

Releases up to v0.8.0-rc.1 ship an unsigned basecamp.exe. Smart App Control only runs code-signed executables — regardless of download source — and has no per-app exceptions, so it blocks the unsigned CLI at launch. Check whether an installed binary is signed with:

Get-AuthenticodeSignature (Get-Command basecamp).Source

Preferred workaround — install inside WSL2, where Smart App Control doesn't apply and your Windows security setup is untouched:

wsl --install

then inside the WSL terminal:

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

The DONE WHEN gate (basecamp --version && basecamp auth status) runs inside WSL in this setup.

Alternative — 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, re-enabling it 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 use WSL2 there instead.

Plain SmartScreen (Smart App Control off) may warn on first run — choose "More info" → "Run anyway".

Termux / Android (SIGSYS: bad system call on startup):

On Termux, the prebuilt binaries and go install github.com/basecamp/basecamp-cli/cmd/basecamp@latest crash immediately — even basecamp --help — with SIGSYS: bad system call. A transitive dependency probes for clipboard tools in its package initializer, and Android's seccomp policy kills the resulting faccessat2 syscall before the program starts. Building from source with Termux's own Go toolchain avoids the blocked syscall:

pkg install golang git
git clone https://github.com/basecamp/basecamp-cli
cd basecamp-cli
go build -o basecamp ./cmd/basecamp   # or: make build → bin/basecamp

Then move the basecamp binary onto your PATH. Requires Go 1.26.7+ — the pinned github.com/basecamp/cli module sets that floor, so lowering the go line in go.mod no longer helps. If your Termux Go is an earlier patch release, upgrade the golang package first (pkg upgrade golang).