basecamp-cli
Basecamp integration for Claude Code. Create todos, track work, link code to projects.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 14 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/basecamp/basecamp-cli with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/basecamp/basecamp-cli'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/basecamp--basecamp-cli)HTML
<a href="/listings/basecamp--basecamp-cli"><img src="/api/listings/basecamp--basecamp-cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
**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](#windows-smart-app-control-and-smartscreen) if the install is blocked.
On an interactive terminal, the installer opens Basecamp setup: approve OAuth in your browser and the CLI uses the account granted by OAuth, otherwise preserves an existing account or selects the first available. It saves that account globally, clears the global project default, and connects every detected coding agent. Directory-specific and environment project settings continue to apply. Use `basecamp setup --customize` to choose those settings instead.
<details> <summary>Other installation methods</summary>
**Brew / macOS**
brew install --cask basecamp/tap/basecamp-cli
**Arch Linux / Omarchy (AUR):**
yay -S basecamp-cli
**Linux (deb/rpm/apk):**
# 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
Arm64: substitute `arm64` for `amd64` in the filename. Verify the SHA-256 checksum from `checksums.txt` before installing unsigned Alpine packages.
**Scoop (Windows):**
scoop bucket add basecamp https://github.com/basecamp/homebrew-tap scoop install basecamp-cli
**Shell script (macOS / Linux / WSL2 / Git Bash):**
curl -fsSL https://raw.githubusercontent.com/basecamp/basecamp-cli/main/scripts/install.sh | bash
**Nix:**
nix profile install github:basecamp/basecamp-cli
**Go install:**
go install github.com/basecamp/basecamp-cli/cmd/basecamp@latest
**mise:**
mise use --global github:basecamp/basecamp-cli@latest
**GitHub Release:** download from [Releases](https://github.com/basecamp/basecamp-cli/releases).
</details>
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/plugin.json · Manifest · 12 lines
- {
- "name": "basecamp-cli",
- "version": "0.30.0",
- "description": "Basecamp integration for Claude Code. Create todos, track work, link code to projects.",
- "author": {
- "name": "37signals",
- "email": "support@37signals.com"
- },
- "homepage": "https://github.com/basecamp/basecamp-cli",
- "repository": "https://github.com/basecamp/basecamp-cli",
- "license": "MIT"
- }
README.md · README · 594 lines · 4 findings marked
- # <img src="assets/bc5-snowglobe.png" height="28" alt="Basecamp"> 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, Grok, 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; Grok Build reads the shared skill directly
- ## Quick Start
- **macOS / Linux / WSL2**
- ```bash
- curl -fsSL https://basecamp.com/install-cli | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 15 on GitHub
- ```
- **Windows (PowerShell)**
- ```powershell
- irm https://raw.githubusercontent.com/basecamp/basecamp-cli/main/scripts/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 21 on GitHub
- ```
- On Windows 11 with Smart App Control, see [Troubleshooting](#windows-smart-app-control-and-smartscreen) if the install is blocked.
- On an interactive terminal, the installer opens Basecamp setup: approve OAuth in your browser and the CLI uses the account granted by OAuth, otherwise preserves an existing account or selects the first available. It saves that account globally, clears the global project default, and connects every detected coding agent. Directory-specific and environment project settings continue to apply. Use `basecamp setup --customize` to choose those settings instead.
- <details>
- <summary>Other installation methods</summary>
- **Brew / macOS**
- ```
- brew install --cask basecamp/tap/basecamp-cli
- ```
- **Arch Linux / Omarchy (AUR):**
- ```bash
- yay -S basecamp-cli
- ```
- **Linux (deb/rpm/apk):**
- ```bash
- # 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
- ```
- Arm64: substitute `arm64` for `amd64` in the filename. Verify the SHA-256 checksum from `checksums.txt` before installing unsigned Alpine packages.
- **Scoop (Windows):**
- ```bash
- scoop bucket add basecamp https://github.com/basecamp/homebrew-tap
- scoop install basecamp-cli
- ```
- **Shell script (macOS / Linux / WSL2 / Git Bash):**
- ```bash
- curl -fsSL https://raw.githubusercontent.com/basecamp/basecamp-cli/main/scripts/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 59 on GitHub
- ```
- **Nix:**
- ```bash
- nix profile install github:basecamp/basecamp-cli
- ```
- **Go install:**
- ```bash
- go install github.com/basecamp/basecamp-cli/cmd/basecamp@latest
- ```
- **mise:**
- ```bash
- mise use --global github:basecamp/basecamp-cli@latest
- ```
- **GitHub Release:** download from [Releases](https://github.com/basecamp/basecamp-cli/releases).
- </details>
- ## Upgrading
- ```bash
- basecamp upgrade
- ```
- What happens depends on how the CLI was installed:
- - **Installer script / tarball** (a binary under your home directory, e.g. `~/bin` or `~/.local/bin`): upgrades in place. The CLI downloads the release for your platform, verifies its Sigstore signature (the keyless `checksums.txt.bundle` published by the release pipeline, identity-pinned to the release workflow and tag) and SHA-256 checksum, swaps the executable transactionally, and confirms the installed binary reports the new version. On failure the previous binary is restored; in the worst case — restoration itself fails mid-swap — the error names the preserved backup file next to the binary so you can put it back by hand.
- - **Homebrew / Scoop**: delegates to `brew upgrade --cask` / `scoop update`, then verifies the manager-installed binary actually reports the new version.
- - **System packages** (apt/dnf/apk, AUR, Nix), **mise**, and **`go install` builds**: never touched. `basecamp upgrade` exits nonzero with upgrade guidance for that install method (the exact command where it can be known, e.g. mise or `go install`; otherwise which package manager to use).
- `basecamp upgrade` exits 0 only when there is no update, or the update was applied *and confirmed*. Every other outcome is a structured failure (`"ok": false` in JSON) with one of these codes:
- | Code | Meaning |
- |---|---|
- | `upgrade_required` | An update exists but the CLI won't apply it for this install method — the hint carries the right next step |
- | `upgrade_incomplete` | The package manager exited 0 but the binary still reports the old version |
- | `upgrade_unverified` | The upgrade may have worked, but the installed version could not be confirmed |
- | `upgrade_failed` | The update check, download, signature/checksum verification, or executable swap failed — the previous binary remains installed (or the error names the preserved backup if restoration also failed) |
- The install scripts verify release signatures when `cosign` is available: cosign v3 verifies the published bundle format as-is, v2.6+ is driven with `--new-bundle-format=true`, and older versions skip signature verification with a warning (SHA-256 checksums are always verified).
- ## First-time setup
- The first interactive `basecamp` run applies the recommended setup automatically after browser approval:
- - Account granted by OAuth, otherwise the existing configured account or first available account, saved globally
- - No global default project; directory-specific and environment project settings continue to apply
- - Every detected Claude Code, Codex or Grok integration
- Run the same setup directly with `basecamp setup`. To choose the account, default project, config scope, and agent integrations, run:
- ```bash
- basecamp setup --customize
- ```
- ## Usage
- ```bash
- 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 pings post Jane "Lunch?" # Ping someone directly
- basecamp comments create 67890 "@Jane.Smith, done!" # Comment with @mention
- ```
- ### Output Formats
- ```bash
- 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:
- ```json
- {
- "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.
- Errors use the same envelope with `ok: false`, a stable `code`, and `retryable`,
- which says whether a retry can change the outcome:
- ```json
- {
- "ok": false,
- "error": "Gateway error (503)",
- "code": "api_error",
- "retryable": true,
- "hint": "..."
- }
- ```
- Key order within the envelope is not part of the contract — the interactive
- (TTY) path re-encodes through a map and alphabetizes keys — so match on key
- names, never on position.
- `retryable` is present on every error envelope — `true` when the CLI classified
- the failure transient (network, timeout, rate limit, circuit open, and most
- 5xx/gateway responses — not all: 507 and some 500s are verdicts), `false` for a
- verdict (usage, not found, auth, forbidden, validation, account limit) and for
- any error nothing classified — and never on a success envelope. Key on it rather
- than on the code or message when deciding whether to retry; `false` means no
- known reason a retry would help, not a guarantee the failure is permanent.
- ## 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.
- ```bash
- basecamp auth login # Authenticate with Basecamp (full access)
- basecamp auth login --scope read # Read-only access (ignored by Launchpad)
- basecamp auth login --scope full # Full read+write access (default; ignored by Launchpad)
- basecamp auth token # Print token for scripts
- ```
- `--expect-identity <id>` makes any login assert who it authenticated as: the
- new credential is checked before it is stored, and on a mismatch nothing is
- written (a profile's previous credential is untouched) and the command exits
- non-zero. `basecamp profile create <name> --expect-identity <id>` does the same
- for a profile that does not exist yet. `--login-hint <email>` names the account to sign in as on the
- device-flow approval page (sent as `login_hint`; it steers the sign-in page and
- never authenticates on its own; ignored by Launchpad).
- ### Personal access tokens
- A [personal access token](https://app.basecamp.com/my/access_tokens) can be
- imported instead of running OAuth — the shape for bots, CI, and any machine
- that should never sign in interactively. The token is read from stdin (never
- an argument), verified against the server — who it authenticates as, and that
- it can reach the profile's account — and only then stored under a named
- profile, with whatever expiry the server reports for it:
- ```bash
- op read "op://Vault/Item/credential" | basecamp auth login --with-token -P bot --account 999
- op read "op://Vault/Item/credential" | basecamp auth login --with-token -P bot --account 999 --expect-identity 12345 --json
- ```
- `--account` is required when the profile does not exist yet. `--json` returns
- an envelope with the profile, account, identity and person, `oauth_type`,
- `scope`, and `expires_at` (the expiry the server reports for the token, or
- `null` when it reports none). A token has no refresh token, so near a reported
- expiry the CLI refuses it and asks for a fresh import.
- ### Agents
- A Basecamp agent is a principal with no person behind it, so it has no browser
- to sign in with and is granted no refresh token. It authenticates with the
- OAuth `client_credentials` grant instead: its client id and secret mint a
- short-lived self-token, and the CLI mints another whenever that one nears
- expiry. The client secret is read from stdin (never an argument) and stored
- with the token it mints — in the OS keyring where one is available — because
- the client, not a refresh token, is what survives an expiry:
- ```bash
- op read "op://Vault/Item/credential" | basecamp auth login --with-client-credentials --client-id <id> -P agent --account 999
- ```
- The login mints once, which is what proves the client id and secret: a refused
- mint stores nothing. `--account` is required when the profile does not exist
- yet. `basecamp auth logout` forgets the credential; there is no useful
- revocation, since the same client would mint another. To end its access,
- disconnect its connection in Basecamp (on My > Agent for your own agent, in
- Adminland for a shared one), which kills that connection's secret and every
- token minted from it. Where My > Agent lists several connections, disconnect
- the one this profile used: Disconnect all ends every one of them.
- ### Connecting an agent to this computer
- You don't paste an agent's secret anywhere: you approve the connection in your
- browser and the CLI keeps the credential. It needs CLI 0.13.0 or later; check
- with `basecamp --version` and run `basecamp upgrade` first if it's older.
- In a terminal, one command does it all:
- ```bash
- basecamp connect setup
- ```
- It connects this computer to your agent (one approval in the browser), records
- who may give it work (for your personal agent, you) and which projects it
- serves, and ends by telling you how to start the connector. If the agent is
- already connected on this computer under a profile, name it
- (`basecamp connect setup -P <profile>`), or setup may connect it again under
- another. The same steps, scriptable:
- ```bash
- basecamp auth agent connect -P my-agent # one approval
- basecamp connect setup -P my-agent --serve 12345 # who may give it work, which projects
- basecamp connect -P my-agent # the watcher
- ```
- Campfires normally require an @mention. For a small Campfire where every
- trusted message should reach the agent, opt it in and restart the connector:
- ```bash
- basecamp chat list --project 12345 -P my-agent --json
- basecamp connect setup -P my-agent --listen-campfire 12345:67890
- ```
- Use the Campfire id from the listing. Existing trust rules still apply, and
- other agents still need mentions. To restore mentions, run setup with
- `--no-listen-campfire 12345:67890` and restart.
- An approval may add a connection or replace an existing one: read the approval
- page before proceeding. Personal and team agents can have several connections
- where Basecamp enables adding them for that kind of agent. Otherwise a new
- approval replaces the existing connection. This applies to both the CLI and
- Basecamp's HTTP handshake. Do not reconnect just to upgrade the CLI.
- Each profile has its own projects, ledger, cursor, hold and local lock. When
- two connections serve the same project, a request both admit can be answered
- twice, so serve each project from one. Use a distinct `--device-name` for each
- profile on the same computer.
- Only one computer should answer an agent's Pings. A Ping is in no project, so
- every connector for the agent sees all of them, and each one that heard them
- would answer. A connector started with `--pings` hears Pings, and anything
- else outside a project; one started with `--no-pings` hears only its projects.
- Without either, the agent's first connection hears them, a connection added
- after it doesn't, and a bot user's login does, as it always has. A run given
- `--project` hears none and saves nothing. The first start without `--project`
- saves the choice for the profile, as either flag saves its own, and restarts
- keep it until you pass the other flag:
- ```bash
- basecamp connect -P desktop --pings # this computer answers Pings
- basecamp connect -P laptop --no-pings # this one leaves them to the desktop
- ```
- A connector that hears Pings warns when another one on the same computer hears
- the same agent's. It can't see other computers, so starting just one there is
- yours to arrange. `basecamp connect status` and `basecamp connect doctor` say
- whether a profile's connector answers them, and why. Where Basecamp lists several connections, you
- can rename them and disconnect one without using Disconnect all. Reconnecting
- a profile on an add-capable server leaves its old connection live until you
- disconnect it; older credential files can remain live too. Do not delete them
- as part of setup. See the [upgrade and downgrade runbook](docs/agent-connections-rollout.md)
- for legacy state adoption and mixed-version precautions.
- In Claude Code, the `/basecamp-connect` skill runs the watcher and hands each
- request to a subagent. It ships in this CLI's plugin from 0.12.0 on, and an
- older plugin doesn't have it. Update the plugin, restart Claude Code, and only
- then remove any older copy of the skill:
- ```bash
- claude plugin update basecamp-cli@37signals # installed as basecamp-cli
- basecamp setup claude # installed under the old name, basecamp@37signals
- ```
- ### Containers, CI and scheduled jobs
- An OAuth login refreshes by rotation: each refresh replaces its refresh token,
- and Basecamp signs the whole login out when a replaced token is used again.
- That is how it notices a stolen one. So one login can be **shared** by many
- processes, but never **copied**: two containers that each hold a copy of
- `credentials.json` sign each other out as soon as both have refreshed more
- than a minute apart, which a retry window forgives but a schedule won't.
- For containers, CI and cron, pick one:
- - **A token that never rotates.** Set `BASECAMP_TOKEN` to a
- [personal access token](#personal-access-tokens), where your account offers
- them, injected as a secret. Nothing refreshes, so every replica can hold the
- same one, and revoking it ends access everywhere.
- - **One shared login, on one host.** Mount one config directory into every
- replica as a read-write volume, with `BASECAMP_NO_KEYRING=1`. The CLI locks
- the login while it refreshes, so replicas take turns instead of signing
- each other out. The lock is an `flock` in that directory, which holds
- between containers on one host. Across hosts, use one of the other two:
- the CLI can't tell a shared filesystem whose `flock` is local to each host,
- and there copies would sign each other out with no warning.
- - **One login per install.** Run `basecamp auth login --device-code` in each
- install, and keep its config directory to itself.
- Never bake `credentials.json` into an image or copy it between machines. The
- CLI says so once, the first time a login refreshes inside a container (again
- later only if it cannot write its marker in the config directory).
- If refreshes keep failing, Basecamp blocks sign-ins from that address for a
- while. The CLI then waits out the block instead of retrying on every run
- (`basecamp auth status` shows the wait), and forgets a revoked login after
- its first refusal; sign in again once whatever was using the old copy has
- stopped.
- ### 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:
- ```bash
- 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):
- | Variable | Purpose |
- |----------|---------|
- | `BASECAMP_OAUTH_CLIENT_ID` | OAuth client ID |
- | `BASECAMP_OAUTH_CLIENT_SECRET` | OAuth client secret |
- | `BASECAMP_OAUTH_REDIRECT_URI` | Redirect URI (must be `http://` loopback with explicit port) |
- Both `BASECAMP_OAUTH_CLIENT_ID` and `BASECAMP_OAUTH_CLIENT_SECRET` must be set together.
- `BASECAMP_OAUTH_ISSUER=https://app.basecamp.com` pins the OAuth authorization
- server and skips discovery, so `basecamp auth login` reaches a server that is
- serving piloted clients but not yet advertising itself (discovery still 404s).
- It is a temporary escape hatch for that dark pilot, not a configuration
- surface, and will be removed once the server advertises its metadata.
- ## 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.
- The plugin hooks additionally need a CLI new enough to carry the `agent-hook`
- command. If hook errors appear after installing or refreshing the plugin, the
- CLI is older than the hooks: run `basecamp upgrade`, then start a new session.
- Check with `basecamp agent-hook --help` — an "unknown command" reply means the
- CLI needs upgrading.
- **Claude Code:** `basecamp setup claude` — installs the plugin with skills, hooks, and agent workflow support.
- **Codex:** `basecamp setup codex` — registers the 37signals marketplace and installs the native plugin with Basecamp skills, diagnostics, and opt-in commit-reference hooks. In Codex, review and trust the plugin hooks with `/hooks`, then start a new thread to load the skills and hooks. The plugin does not inject Basecamp context at session start (beyond a pointer to `basecamp instructions` when instructions are set, plus their gist when it can be read without the network); Codex selects the skill when a request is relevant or explicitly references Basecamp.
- Manual Codex installation uses the same marketplace:
- ```bash
- codex plugin marketplace add basecamp/claude-plugins
- codex plugin add basecamp-cli@37signals
- ```
- To pick up a newer plugin version later, refresh the marketplace with
- `codex plugin marketplace upgrade 37signals` (or re-run `basecamp setup codex`).
- **Plugin name:** in the 37signals marketplace this plugin is `basecamp-cli`
- (`basecamp-cli@37signals`). It was published as `basecamp`, a name set aside
- for the hosted Basecamp connector plugin, which works through Basecamp's own
- MCP server rather than this CLI. During a deprecation window the marketplace
- keeps `basecamp` as an alias of `basecamp-cli`, so an existing
- `basecamp@37signals` install keeps working and updating; once per agent it
- says the plugin has been renamed. Switch with `basecamp setup claude` or
- `basecamp setup codex` (or `basecamp setup agents`). For Claude Code, setup
- replaces `basecamp@37signals` with `basecamp-cli` at the scopes it was
- installed in. Codex installs have no scopes, so setup adds `basecamp-cli` and
- then removes the old ID. To switch by hand:
- ```bash
- claude plugin marketplace update 37signals
- claude plugin install basecamp-cli@37signals
- claude plugin uninstall basecamp@37signals
- codex plugin marketplace upgrade 37signals
- codex plugin add basecamp-cli@37signals
- codex plugin remove basecamp@37signals
- ```
- Skills from the plugin are namespaced by its name, so `basecamp:basecamp`
- becomes `basecamp-cli:basecamp`. The CLI itself is still `basecamp`.
- **Grok Build:** `basecamp setup grok` — installs the shared 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 `~/.agents/skills/basecamp` skill is the whole integration. Grok is detected by `$GROK_HOME` (default `~/.grok`) or a `grok` binary on `PATH`, in `~/.local/bin`, or in `$GROK_HOME/bin` where its installers put it. Start a new Grok session after setup to load the skill.
- **Other agents:** Point your agent at [`skills/basecamp/SKILL.md`](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](install.md) for step-by-step setup instructions.
- ### MCP Server
- `basecamp mcp` runs an MCP (Model Context Protocol) server on stdin/stdout,
- serving Basecamp as tools backed by your signed-in account — no separate
- binary or extra credentials. Register it with any MCP client as a stdio
- server:
- ```bash
- claude mcp add basecamp -- basecamp mcp
- ```
- Sixteen domain tools (`basecamp_projects`, `basecamp_todos`, `basecamp_cards`,
- `basecamp_messages`, `basecamp_campfires`, `basecamp_boosts`,
- `basecamp_schedules`, `basecamp_files`, `basecamp_people`,
- `basecamp_automation`, `basecamp_reports`, `basecamp_everything`,
- `basecamp_clientside`, `basecamp_forwards`, `basecamp_account`,
- `basecamp_recordings`) cover the Basecamp API, scoped to the configured
- account. Each tool takes `{"action": "...", "params": {...}}` and serves
- per-action schemas through its `describe` action.
- Composite helpers ride on that surface, shared with basecamp-mcp-server
- through basecamp-sdk so both servers answer the same way.
- `basecamp_recordings summarize` resolves the pointer an account event feed
- row carries — bucket id, recording id, and the event or recording type —
- into one compact projection, discovering a chat line's Campfire on the way.
- It is not backed by any single Basecamp endpoint, and the catalogue says so:
- it carries no method and no path, where every model operation carries both,
- and its summary opens with "Synthetic:". `basecamp_messages create_comment`
- is an ordinary endpoint with a synthetic parameter: `mentions`, a list of
- person ids expanded client-side into the attachment markup Basecamp reads as
- a mention. `basecamp_recordings move` and `copy` file a recording into
- another container, in its project or another one, as the web's Move… and
- Copy… dialogs do: they wait for Basecamp to finish and return the new
- recording, and a failure says whether trying again is safe.
- ```bash
- basecamp mcp --read-only # serve only read-only actions
- basecamp mcp --domains projects,todos # narrow the served surface (fails closed on unknown keys)
- ```
- ## 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.
- ### Trusting repository configuration
- Repository and local configs may set ordinary defaults such as `project_id`
- and `todolist_id` without approval. Settings that control connections, including
- `base_url`, `profiles`, and `default_profile`, require explicit trust:
- ```bash
- basecamp config trust /path/to/.basecamp/config.json
- ```
- Review the file and its server addresses before trusting it. Trust applies to
- its current security-sensitive settings, not just its path. If those settings
- change, the CLI ignores them and warns until you review and trust the file
- again. Formatting changes and changes to ordinary top-level defaults retain
- trust.
- **Upgrading from path-only trust:** previously trusted configs must be reviewed
- and trusted again before their security-sensitive settings apply. Global
- configuration and saved credentials are unchanged. Until reapproval, trust-gated
- connection, cache, and LLM settings are ignored, including `base_url`, `profiles`,
- `default_profile`, `cache_dir`, `cache_enabled`, and LLM provider, endpoint, model,
- and budget settings. Ordinary top-level defaults such as `account_id`,
- `project_id`, and `todolist_id` still apply. Check the effective server address,
- account, and project with `basecamp config show` before making changes.
- ## Troubleshooting
- ```bash
- basecamp doctor # Check CLI health and diagnose issues
- basecamp doctor --verbose # Verbose output with details
- basecamp doctor --json # Structured checks, including Claude, Codex and Grok
- ```
- ### 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:
- ```powershell
- 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`
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 567 on GitHub
- 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
- ```bash
- 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](CONTRIBUTING.md) for development setup.
- ## License
- [MIT](MIT-LICENSE)
scripts/install.ps1 · Bundled script · 479 lines · 2 findings marked
- $ErrorActionPreference = 'Stop'
- try {
- [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
- } catch {
- # Ignore when the runtime manages TLS defaults.
- }
- # Environment options:
- # BASECAMP_VERSION Specific version to install (default: latest)
- # BASECAMP_BIN_DIR Where to install the binary
- # BASECAMP_SKIP_SETUP Set to 1 to skip first-time setup (still runs
- # `basecamp setup agents`)
- # BASECAMP_NONINTERACTIVE
- # Set to 1 or true to use non-interactive setup
- # BASECAMP_SETUP_AGENT Which coding agent(s) `setup agents` connects:
- # claude | codex | grok | all | none. Unset = auto-detect.
- # Piped install sets it for the interpreter, not the fetch:
- # $env:BASECAMP_SETUP_AGENT='codex'; irm https://raw.githubusercontent.com/basecamp/basecamp-cli/main/scripts/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 19 on GitHub
- $Repo = 'basecamp/basecamp-cli'
- $Version = $env:BASECAMP_VERSION
- $SkipSetup = $env:BASECAMP_SKIP_SETUP
- $BinDir = $env:BASECAMP_BIN_DIR
- function Step([string]$Message) {
- Write-Host " -> $Message"
- }
- function Info([string]$Message) {
- Write-Host " + $Message" -ForegroundColor Green
- }
- function Warn([string]$Message) {
- Write-Warning $Message
- }
- function Test-TruthyEnvironmentValue([string]$Value) {
- return $Value -match '^(?i:1|true)$'
- }
- function Fail([string]$Message) {
- throw $Message
- }
- function Get-PlatformArch {
- $arch = $env:PROCESSOR_ARCHITECTURE
- if ($env:PROCESSOR_ARCHITEW6432) {
- $arch = $env:PROCESSOR_ARCHITEW6432
- }
- switch -Regex ($arch) {
- '^(AMD64|x86_64)$' { return 'amd64' }
- '^ARM64$' { return 'arm64' }
- default { Fail "Unsupported Windows architecture: $arch" }
- }
- }
- function Get-LatestVersion {
- Step 'Resolving latest release version...'
- # Follow the releases/latest redirect first to avoid GitHub API rate limits.
- # -MaximumRedirection 0 turns the expected 302 into a terminating error, so
- # we read Location off the caught response. Headers.Location is Uri on
- # PowerShell Core and string on Windows PowerShell 5.1, so coerce to string.
- $location = $null
- try {
- $response = Invoke-WebRequest -MaximumRedirection 0 -UseBasicParsing `
- -Headers @{ 'User-Agent' = 'basecamp-cli-installer' } `
- -Uri "https://github.com/$Repo/releases/latest" -ErrorAction Stop
- $location = $response.Headers.Location
- } catch {
- if ($_.Exception.Response) {
- $location = $_.Exception.Response.Headers.Location
- if (-not $location) {
- $location = $_.Exception.Response.Headers['Location']
- }
- }
- }
- if ($location) {
- $tag = ([string]$location).TrimEnd('/').Split('/')[-1]
- $candidate = $tag.TrimStart('v')
- if ($candidate -match '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$') {
- return $candidate
- }
- }
- # Fall back to the GitHub API if the redirect path didn't yield a semver tag.
- $release = Invoke-RestMethod -ErrorAction Stop `
- -Headers @{ 'User-Agent' = 'basecamp-cli-installer' } `
- -Uri "https://api.github.com/repos/$Repo/releases/latest"
- if (-not $release.tag_name) {
- Fail 'Could not determine latest release version from GitHub.'
- }
- return $release.tag_name.TrimStart('v')
- }
- function Download-File([string]$Url, [string]$Destination) {
- # -UseBasicParsing avoids initializing IE's MSHTML parser on Windows
- # PowerShell 5.1 -- required on Server Core and locked-down installs.
- # No-op on PowerShell 6+, where basic parsing is the only mode.
- Invoke-WebRequest -UseBasicParsing -ErrorAction Stop `
- -Headers @{ 'User-Agent' = 'basecamp-cli-installer' } `
- -Uri $Url -OutFile $Destination
- }
- function Verify-Checksum([string]$ChecksumsPath, [string]$ArchivePath, [string]$ArchiveName) {
- $expected = $null
- foreach ($line in Get-Content $ChecksumsPath) {
- if ($line -match '^(?<hash>[0-9a-fA-F]{64})\s+\*?(?<name>.+)$') {
- if ($Matches.name -eq $ArchiveName) {
- $expected = $Matches.hash.ToLowerInvariant()
- break
- }
- }
- }
- if (-not $expected) {
- Fail "Could not find checksum entry for $ArchiveName"
- }
- $actual = (Get-FileHash -Algorithm SHA256 -Path $ArchivePath).Hash.ToLowerInvariant()
- if ($actual -ne $expected) {
- Fail "Checksum verification failed for $ArchiveName"
- }
- Info 'Checksum verified'
- }
- # Get-CosignBundleSupport decides how to verify the release's Sigstore bundle,
- # which is the new (protobuf, v0.3+json) format:
- # v3+ -> new-format parsing is the default; no extra flag ('')
- # v2.6 - v2.x -> needs '--new-bundle-format=true' (v2.x defaults it to false)
- # < v2.6 / unparseable -> $null: cannot verify (v2.4 chokes on the bundle's
- # tlog key type, v2.2 lacks the flag); caller warns and skips
- function Get-CosignBundleSupport {
- try { $versionOutput = & cosign version 2>$null } catch { return $null }
- foreach ($line in @($versionOutput)) {
- if ("$line" -match 'GitVersion:\s*v?(\d+)\.(\d+)\.') {
- $major = [int]$Matches[1]
- $minor = [int]$Matches[2]
- if ($major -ge 3) { return '' }
- if ($major -eq 2 -and $minor -ge 6) { return '--new-bundle-format=true' }
- return $null
- }
- }
- return $null
- }
- function Verify-CosignSignature([string]$Version, [string]$BaseUrl, [string]$TmpDir) {
- if (-not (Get-Command cosign -ErrorAction SilentlyContinue)) {
- return
- }
- $bundleFlag = Get-CosignBundleSupport
- if ($null -eq $bundleFlag) {
- Step "Skipping signature verification: this cosign can't verify the release bundle format (need cosign >= 2.6)"
- return
- }
- Step 'Verifying cosign signature...'
- $bundlePath = Join-Path $TmpDir 'checksums.txt.bundle'
- $checksumsPath = Join-Path $TmpDir 'checksums.txt'
- Download-File -Url "$BaseUrl/checksums.txt.bundle" -Destination $bundlePath
- $cosignArgs = @('verify-blob', '--bundle', $bundlePath)
- if ($bundleFlag) {
- $cosignArgs += $bundleFlag
- }
- $cosignArgs += @(
- '--certificate-identity', "https://github.com/basecamp/basecamp-cli/.github/workflows/release.yml@refs/tags/v$Version",
- '--certificate-oidc-issuer', 'https://token.actions.githubusercontent.com',
- $checksumsPath
- )
- # Native exits don't trigger ErrorActionPreference=Stop on Windows PowerShell 5.1,
- # so check $LASTEXITCODE explicitly -- otherwise a verify failure would false-green.
- & cosign @cosignArgs
- if ($LASTEXITCODE -ne 0) {
- Fail 'Cosign signature verification failed'
- }
- Info 'Signature verified'
- }
- # Get-FirstRunFailureMessage diagnoses why running the freshly installed
- # basecamp.exe failed. It best-effort probes the binary's Authenticode status
- # and the Smart App Control state (releases up to v0.8.0-rc.1 ship an unsigned
- # basecamp.exe, which Smart App Control blocks at process creation). Every
- # branch leads with the original failure: diagnosis augments, never masks,
- # the underlying error. PowerShell 5.1-compatible.
- function Get-FirstRunFailureMessage([string]$Binary, [string]$Reason) {
- $sigStatus = $null
- try {
- $sigStatus = (Get-AuthenticodeSignature -FilePath $Binary -ErrorAction Stop).Status
- } catch { }
- # Smart App Control state: 0 = off, 1 = on, 2 = evaluation mode.
- $sacState = $null
- try {
- $policy = Get-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\CI\Policy' -ErrorAction Stop
- $sacState = $policy.VerifiedAndReputablePolicyState
- } catch { }
- $lead = "Installed basecamp.exe to $Binary, but running it failed: $Reason"
- if ("$sigStatus" -eq 'NotSigned' -and ($sacState -eq 1 -or $sacState -eq 2)) {
- return @"
- $lead
- This build of basecamp.exe is not code-signed, and Smart App Control is enabled. Smart App Control blocks unsigned executables no matter where they were downloaded from, and it has no per-app exceptions. Two options:
- 1. (Preferred) Install the Linux build inside WSL2 - Smart App Control does not apply there and your Windows security setup is untouched:
- wsl --install
- then, inside the WSL terminal:
- curl -fsSL https://basecamp.com/install-cli | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 220 on GitHub
- 2. Turn Smart App Control off (Windows Security > App & browser control > Smart App Control settings) and leave it off while using this 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 release. 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 the WSL2 option there.
- "@
- }
- if ("$sigStatus" -eq 'NotSigned') {
- return @"
- $lead
- This build of basecamp.exe is not code-signed, and Windows Security or SmartScreen may have blocked or quarantined it. Check Windows Security > Protection history for a block or quarantine event, restore or allow basecamp.exe, then re-run the installer.
- "@
- }
- return @"
- $lead
- If Windows Security or antivirus interfered, check Windows Security > Protection history, restore or allow basecamp.exe, then re-run the installer.
- "@
- }
- function Get-PathEntries {
- param([string]$PathValue)
- if (-not $PathValue) {
- return @()
- }
- return $PathValue -split ';' | Where-Object { $_ }
- }
- function Normalize-PathEntry([string]$PathValue) {
- if (-not $PathValue) {
- return ''
- }
- return $PathValue.Trim().TrimEnd('\\')
- }
- function Get-DefaultBinDir {
- $currentPathEntries = Get-PathEntries $env:Path
- $userPathEntries = Get-PathEntries ([Environment]::GetEnvironmentVariable('Path', 'User'))
- $allEntries = @($currentPathEntries + $userPathEntries) | ForEach-Object { Normalize-PathEntry $_ }
- $homeBin = Normalize-PathEntry (Join-Path $HOME 'bin')
- $homeLocalBin = Normalize-PathEntry (Join-Path $HOME '.local\bin')
- if ($allEntries -contains $homeBin) {
- return $homeBin
- }
- if ($allEntries -contains $homeLocalBin) {
- return $homeLocalBin
- }
- return $homeBin
- }
- function Ensure-UserPath([string]$Dir) {
- $userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
- $segments = Get-PathEntries $userPath
- $normalizedSegments = $segments | ForEach-Object { Normalize-PathEntry $_ }
- $normalizedDir = Normalize-PathEntry $Dir
- if ($normalizedSegments -contains $normalizedDir) {
- return
- }
- $newPath = if ($userPath) { "$Dir;$userPath" } else { $Dir }
- [Environment]::SetEnvironmentVariable('Path', $newPath, 'User')
- $env:Path = "$Dir;$env:Path"
- Info "Added $Dir to your user PATH"
- }
- function Test-InteractiveSession {
- if ($Host.Name -ne 'ConsoleHost' -and $Host.Name -ne 'Visual Studio Code Host') {
- return $false
- }
- try {
- return -not [Console]::IsInputRedirected -and
- -not [Console]::IsOutputRedirected -and
- -not [Console]::IsErrorRedirected
- } catch {
- return $false
- }
- }
- # Invoke-FirstTimeSetup runs optional onboarding without changing the successful
- # installation result. The native process inherits the console streams so setup
- # can render and pass its terminal-safety gate.
- function Invoke-FirstTimeSetup([string]$Binary) {
- try {
- & $Binary setup
- if ($LASTEXITCODE -eq 0) {
- return
- }
- } catch {
- # The retry guidance below covers process-launch and command failures alike.
- }
- Warn 'First-time setup did not finish. Run it again with: basecamp setup'
- }
- # Invoke-PostInstallSetup installs the baseline skill and connects coding agents
- # without prompting, honoring BASECAMP_SETUP_AGENT (claude|codex|grok|all|none;
- # unset = auto-detect). It is strictly best-effort: agent setup must never fail
- # an otherwise-successful install, so every native call is wrapped so a nonzero
- # exit (amplified by $ErrorActionPreference='Stop' +
- # $PSNativeCommandUseErrorActionPreference) cannot terminate the installer.
- #
- # Cross-version: newer binaries expose the intent-neutral `setup agents`. Older
- # release binaries (the hosted install.ps1 from main can outrun the latest
- # release) fall back WITHOUT reintroducing the Claude-first bug -- only an
- # *explicitly* selected agent is connected. `all` runs every per-agent setup the
- # binary supports; unset/auto/ambiguous installs the shared skill only. Each
- # native call is individually guarded so a nonzero exit never aborts the install.
- function Invoke-PostInstallSetup([string]$Binary) {
- # None of these calls touch credentials, but release binaries up to v0.7.2
- # probe the OS keyring on startup for every command, and a locked headless
- # keychain blocks that probe forever. Set the escape hatch for the duration
- # of setup only, restoring the caller's value (or absence) on the way out.
- $savedNoKeyring = $env:BASECAMP_NO_KEYRING
- $env:BASECAMP_NO_KEYRING = '1'
- try {
- try { $help = & $Binary setup --help 2>$null } catch { $help = '' }
- if ($help -match '(?m)^\s+agents\s') {
- try { & $Binary setup agents } catch { }
- return
- }
- $selector = $env:BASECAMP_SETUP_AGENT
- if ($selector -in @('claude', 'codex', 'grok')) {
- # Capability-check first: an old `setup` parent accepts an unadvertised agent
- # id as a stray arg and launches the INTERACTIVE wizard. Degrade to the skill.
- if ($help -match "(?m)^\s+$selector\s") {
- try { & $Binary setup $selector } catch { }
- } else {
- try { & $Binary skill install } catch { }
- }
- } elseif ($selector -eq 'all') {
- $ranAgent = $false
- foreach ($agent in @('claude', 'codex', 'grok')) {
- if ($help -match "(?m)^\s+$agent\s") {
- # Mark attempted (not succeeded) -- matches install.sh's `ran_agent=1`,
- # which is set regardless of the setup call's exit status.
- $ranAgent = $true
- try { & $Binary setup $agent } catch { }
- }
- }
- if (-not $ranAgent) { try { & $Binary skill install } catch { } }
- } else {
- try { & $Binary skill install } catch { }
- }
- } finally {
- $env:BASECAMP_NO_KEYRING = $savedNoKeyring
- }
- }
- function Main {
- $arch = Get-PlatformArch
- if (-not $BinDir) {
- $script:BinDir = Get-DefaultBinDir
- }
- $resolvedVersion = if ($Version) { $Version } else { Get-LatestVersion }
- if ($resolvedVersion -notmatch '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$') {
- Fail "Invalid version '$resolvedVersion'. Expected semver format like 1.2.3 or 1.2.3-rc.1."
- }
- $archiveName = "basecamp_${resolvedVersion}_windows_${arch}.zip"
- $baseUrl = "https://github.com/$Repo/releases/download/v$resolvedVersion"
- Step "Downloading basecamp v$resolvedVersion for windows_$arch..."
- $tmpDir = Join-Path ([IO.Path]::GetTempPath()) ([IO.Path]::GetRandomFileName())
- New-Item -ItemType Directory -Path $tmpDir | Out-Null
- try {
- $archivePath = Join-Path $tmpDir $archiveName
- $checksumsPath = Join-Path $tmpDir 'checksums.txt'
- $extractDir = Join-Path $tmpDir 'extract'
- Download-File -Url "$baseUrl/$archiveName" -Destination $archivePath
- Step 'Verifying checksums...'
- Download-File -Url "$baseUrl/checksums.txt" -Destination $checksumsPath
- Verify-Checksum -ChecksumsPath $checksumsPath -ArchivePath $archivePath -ArchiveName $archiveName
- Verify-CosignSignature -Version $resolvedVersion -BaseUrl $baseUrl -TmpDir $tmpDir
- Step 'Extracting...'
- Expand-Archive -Path $archivePath -DestinationPath $extractDir -Force
- $binaryPath = Join-Path $extractDir 'basecamp.exe'
- if (-not (Test-Path $binaryPath)) {
- Fail 'basecamp.exe not found in archive. If Windows Security or antivirus removed it during extraction, check Windows Security > Protection history, restore it, and re-run the installer.'
- }
- $installedBinary = Join-Path $BinDir 'basecamp.exe'
- New-Item -ItemType Directory -Force -Path $BinDir | Out-Null
- # Windows holds an exclusive lock on running PE files; -Force doesn't help.
- # Generic catch -- typed catches miss ActionPreferenceStopException wrapping.
- try {
- Copy-Item -Force $binaryPath $installedBinary -ErrorAction Stop
- } catch {
- Fail "Failed to install basecamp.exe. If it is in use, close any running 'basecamp' processes and re-run the installer. If Windows Security quarantined it, check Windows Security > Protection history and restore it. (Original error: $($_.Exception.Message))"
- }
- Ensure-UserPath -Dir $BinDir
- Info "Installed basecamp to $installedBinary"
- # Smart App Control kills CreateProcess for unsigned executables, so the
- # first run is where a block surfaces. Generic catch per the Copy-Item
- # precedent above.
- try {
- $installedVersion = & $installedBinary --version
- } catch {
- Fail (Get-FirstRunFailureMessage -Binary $installedBinary -Reason $_.Exception.Message)
- }
- Info "$installedVersion installed"
- $isInteractive = Test-InteractiveSession
- Write-Host ''
- if ($SkipSetup -eq '1') {
- Step 'Skipping first-time setup (BASECAMP_SKIP_SETUP=1)'
- # Still install the baseline skill and connect coding agents (best-effort).
- Invoke-PostInstallSetup $installedBinary
- Write-Host ''
- Write-Host ' Next steps:'
- Write-Host ' basecamp auth login Authenticate with Basecamp'
- Write-Host ' basecamp setup Run first-time setup'
- Write-Host ''
- } elseif ($isInteractive -and -not (Test-TruthyEnvironmentValue $env:BASECAMP_NONINTERACTIVE)) {
- Invoke-FirstTimeSetup $installedBinary
- } else {
- if (Test-TruthyEnvironmentValue $env:BASECAMP_NONINTERACTIVE) {
- Info 'Skipping first-time setup because BASECAMP_NONINTERACTIVE is enabled.'
- } else {
- Info 'Skipping first-time setup because PowerShell is running non-interactively.'
- }
- # Install the baseline skill and connect coding agents (best-effort).
- Invoke-PostInstallSetup $installedBinary
- Write-Host ''
- Write-Host ' Installed executable:'
- Write-Host " $installedBinary"
- Write-Host ''
- Write-Host ' In this session, use the installed executable path directly for follow-up actions like starting login.'
- Write-Host ''
- }
- }
- finally {
- if (Test-Path $tmpDir) {
- Remove-Item -Recurse -Force $tmpDir
- }
- }
- }
- Main
scripts/install.sh · Bundled script · 647 lines · 2 findings marked
- #!/usr/bin/env bash
- # install.sh - Install basecamp CLI
- #
- # Usage:
- # curl -fsSL https://raw.githubusercontent.com/basecamp/basecamp-cli/main/scripts/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 5 on GitHub
- #
- # Options (via environment):
- # BASECAMP_BIN_DIR Where to install binary
- # (default: ~/bin if on PATH, else ~/.local/bin if on PATH;
- # otherwise ~/bin on Windows, ~/.local/bin elsewhere)
- # BASECAMP_VERSION Specific version to install (default: latest)
- # BASECAMP_SKIP_SETUP Set to 1 to skip first-time setup after install
- # (still runs `basecamp setup agents` to install the skill
- # and connect coding agents)
- # BASECAMP_NONINTERACTIVE
- # Set to 1 or true to use non-interactive setup
- # (still runs `basecamp setup agents` to install the skill
- # and connect coding agents)
- # BASECAMP_SETUP_AGENT
- # Which coding agent(s) `setup agents` connects:
- # claude | codex | grok | all | none. Unset = auto-detect (connect
- # a single detected agent; if several, install the skill
- # only and surface the per-agent commands).
- # Piped install sets it for the interpreter, not the fetch:
- # curl -fsSL https://basecamp.com/install-cli | BASECAMP_SETUP_AGENT=codex bash
- set -euo pipefail
- REPO="basecamp/basecamp-cli"
- BIN_DIR="${BASECAMP_BIN_DIR:-}"
- VERSION="${BASECAMP_VERSION:-}"
- CURL_SCHANNEL_FALLBACK_FLAG=""
- CURL_LAST_ERROR=""
- CURL_FALLBACK_NOTED=0
- # Color helpers — respect NO_COLOR (https://no-color.org)
- if [[ -z "${NO_COLOR:-}" ]] && [[ -t 1 ]]; then
- bold() { printf '\033[1m%s\033[0m' "$1"; }
- green() { printf '\033[32m%s\033[0m' "$1"; }
- red() { printf '\033[31m%s\033[0m' "$1"; }
- dim() { printf '\033[2m%s\033[0m' "$1"; }
- else
- bold() { printf '%s' "$1"; }
- green() { printf '%s' "$1"; }
- red() { printf '%s' "$1"; }
- dim() { printf '%s' "$1"; }
- fi
- info() { echo " $(green "✓") $1"; }
- step() { echo " $(bold "→") $1"; }
- warn() { echo " $(bold "!") $1" >&2; }
- error() { echo " $(red "✗ ERROR:") $1" >&2; exit 1; }
- env_value_is_true() {
- case "$1" in
- 1|[Tt][Rr][Uu][Ee]) return 0 ;;
- *) return 1 ;;
- esac
- }
- can_run_first_time_setup() {
- ! env_value_is_true "${BASECAMP_NONINTERACTIVE:-}" &&
- [[ -t 1 ]] && [[ -t 2 ]] && { : </dev/tty; } 2>/dev/null
- }
- run_first_time_setup() {
- local binary="$1"
- if "$binary" setup; then
- return 0
- fi
- warn "First-time setup did not finish. Run it again with: basecamp setup"
- }
- find_sha256_cmd() {
- if command -v sha256sum &>/dev/null; then
- echo "sha256sum"
- elif command -v shasum &>/dev/null; then
- echo "shasum -a 256"
- else
- error "No SHA256 tool found (need sha256sum or shasum)"
- fi
- }
- # NOTE: Keep the installer helper functions below in sync with scripts/ensure-basecamp.sh.
- # These scripts stay self-contained on purpose so they can run without sourcing extra files.
- path_contains_dir() {
- local dir="$1"
- [[ ":$PATH:" == *":$dir:"* ]]
- }
- default_bin_dir() {
- local platform="$1"
- if path_contains_dir "$HOME/bin"; then
- echo "$HOME/bin"
- return 0
- fi
- if path_contains_dir "$HOME/.local/bin"; then
- echo "$HOME/.local/bin"
- return 0
- fi
- if [[ "$platform" == windows_* ]]; then
- echo "$HOME/bin"
- else
- echo "$HOME/.local/bin"
- fi
- }
- detect_platform() {
- local os arch
- os=$(uname -s | tr '[:upper:]' '[:lower:]')
- case "$os" in
- darwin) os="darwin" ;;
- linux) os="linux" ;;
- freebsd) os="freebsd" ;;
- openbsd) os="openbsd" ;;
- mingw*|msys*|cygwin*) os="windows" ;;
- *) error "Unsupported OS: $os" ;;
- esac
- arch=$(uname -m)
- case "$arch" in
- x86_64|amd64) arch="amd64" ;;
- aarch64|arm64) arch="arm64" ;;
- *) error "Unsupported architecture: $arch" ;;
- esac
- echo "${os}_${arch}"
- }
- detect_curl_fallback() {
- local version_output help_output
- version_output=$(curl --version 2>/dev/null || true)
- if [[ "$version_output" != *[Ss]channel* ]]; then
- return 0
- fi
- help_output=$(curl --help all 2>/dev/null || true)
- if [[ "$help_output" == *"--ssl-revoke-best-effort"* ]]; then
- CURL_SCHANNEL_FALLBACK_FLAG="--ssl-revoke-best-effort"
- elif [[ "$help_output" == *"--ssl-no-revoke"* ]]; then
- CURL_SCHANNEL_FALLBACK_FLAG="--ssl-no-revoke"
- fi
- }
- curl_run() {
- # --show-error guarantees curl writes errors to stderr even if a future caller
- # passes -s without -S. The Schannel revocation detection below depends on
- # finding CRYPT_E_NO_REVOCATION_CHECK in stderr; without --show-error a -s
- # caller would silently lose the fallback.
- local err_file status err
- err_file=$(mktemp "${TMPDIR:-/tmp}/basecamp-curl.XXXXXX")
- if curl --show-error "$@" 2>"$err_file"; then
- rm -f "$err_file"
- CURL_LAST_ERROR=""
- return 0
- else
- status=$?
- fi
- err=$(<"$err_file")
- rm -f "$err_file"
- if [[ $status -ne 0 ]] && [[ -n "$CURL_SCHANNEL_FALLBACK_FLAG" ]] && [[ "$err" == *"CRYPT_E_NO_REVOCATION_CHECK"* ]]; then
- if [[ $CURL_FALLBACK_NOTED -eq 0 ]]; then
- echo " $(bold "→") Windows certificate revocation checks are unavailable; retrying curl with ${CURL_SCHANNEL_FALLBACK_FLAG}" >&2
- CURL_FALLBACK_NOTED=1
- fi
- err_file=$(mktemp "${TMPDIR:-/tmp}/basecamp-curl.XXXXXX")
- if curl --show-error "$CURL_SCHANNEL_FALLBACK_FLAG" "$@" 2>"$err_file"; then
- rm -f "$err_file"
- CURL_LAST_ERROR=""
- return 0
- else
- status=$?
- fi
- err=$(<"$err_file")
- rm -f "$err_file"
- fi
- CURL_LAST_ERROR="$err"
- return "$status"
- }
- get_latest_version() {
- local url version api_json
- # Follow the releases/latest redirect to get the version from the final URL.
- # Avoids the GitHub API (no rate limiting) and grep/sed (better Windows compat).
- if url=$(curl_run -fsSL -o /dev/null -w '%{url_effective}' "https://github.com/${REPO}/releases/latest"); then
- version="${url##*/}"
- version="${version#v}"
- if [[ $version =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
- echo "$version"
- return 0
- fi
- fi
- # Fallback to the GitHub API if redirect parsing fails. Whitespace-tolerant
- # regex so a future GitHub format change (pretty-print, extra spaces) doesn't
- # silently break the fallback. Pure bash so no GNU-awk dependency.
- if api_json=$(curl_run -fsSL -H 'Accept: application/vnd.github+json' -H 'User-Agent: basecamp-cli-installer' "https://api.github.com/repos/${REPO}/releases/latest"); then
- if [[ $api_json =~ \"tag_name\"[[:space:]]*:[[:space:]]*\"v?([^\"]+)\" ]]; then
- version="${BASH_REMATCH[1]}"
- if [[ $version =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
- echo "$version"
- return 0
- fi
- fi
- fi
- error "Could not determine latest version. ${CURL_LAST_ERROR:+curl said: ${CURL_LAST_ERROR}. }If native Windows curl fails, try Scoop or PowerShell. If using Git Bash, try /usr/bin/curl instead."
- }
- # cosign_version prints the installed cosign's version (e.g. "v2.6.0"), empty
- # when it can't be determined. The trailing `|| true` is load-bearing: under
- # `set -euo pipefail` a broken cosign (nonzero `cosign version`) would
- # otherwise abort the whole installer from inside the caller's command
- # substitution — an unusable cosign must degrade to warn-and-skip, not abort.
- cosign_version() {
- cosign version 2>/dev/null | awk -F': *' '/^GitVersion/ {print $2; exit}' || true
- }
- # cosign_bundle_support decides how to verify the release's Sigstore bundle,
- # which is the new (protobuf, v0.3+json) format. Prints the extra verify-blob
- # flag to use ("" for none) and returns 0 when verification can proceed:
- # v3+ → new-format parsing is the default; no flag
- # v2.6 – v2.x → needs --new-bundle-format=true (v2.x defaults it to false)
- # < v2.6 → cannot verify (v2.4 chokes on the bundle's tlog key type,
- # v2.2 lacks the flag entirely); caller warns and skips
- cosign_bundle_support() {
- local version="$1" major minor
- if [[ "$version" =~ ^v?([0-9]+)\.([0-9]+)\. ]]; then
- major="${BASH_REMATCH[1]}"
- minor="${BASH_REMATCH[2]}"
- else
- return 1
- fi
- if (( major >= 3 )); then
- echo ""
- elif (( major == 2 && minor >= 6 )); then
- echo "--new-bundle-format=true"
- else
- return 1
- fi
- }
- verify_checksums() {
- local version="$1"
- local tmp_dir="$2"
- local archive_name="$3"
- local base_url="https://github.com/${REPO}/releases/download/v${version}"
- step "Verifying checksums..."
- if ! curl_run -fsSL "${base_url}/checksums.txt" -o "${tmp_dir}/checksums.txt"; then
- error "Failed to download checksums.txt${CURL_LAST_ERROR:+ (${CURL_LAST_ERROR})}"
- fi
- # Verify SHA256 checksum of the downloaded archive
- local expected actual
- expected=$(awk -v f="$archive_name" '$2 == f || $2 == ("*" f) {print $1; exit}' "${tmp_dir}/checksums.txt")
- actual=$(cd "$tmp_dir" && $(find_sha256_cmd) "$archive_name" | awk '{print $1}')
- [[ -n "$expected" && "$expected" == "$actual" ]] \
- || error "Checksum verification failed for $archive_name"
- info "Checksum verified"
- # If cosign is available and understands the bundle format, verify the signature
- if command -v cosign &>/dev/null; then
- local cosign_ver bundle_flag
- cosign_ver=$(cosign_version)
- if bundle_flag=$(cosign_bundle_support "$cosign_ver"); then
- step "Verifying cosign signature..."
- if ! curl_run -fsSL "${base_url}/checksums.txt.bundle" -o "${tmp_dir}/checksums.txt.bundle"; then
- error "Failed to download checksums.txt.bundle${CURL_LAST_ERROR:+ (${CURL_LAST_ERROR})}"
- fi
- local -a cosign_args=(verify-blob --bundle "${tmp_dir}/checksums.txt.bundle")
- if [[ -n "$bundle_flag" ]]; then
- cosign_args+=("$bundle_flag")
- fi
- cosign_args+=( \
- --certificate-identity "https://github.com/basecamp/basecamp-cli/.github/workflows/release.yml@refs/tags/v${version}" \
- --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
- "${tmp_dir}/checksums.txt")
- cosign "${cosign_args[@]}" \
- || error "Cosign signature verification failed"
- info "Signature verified"
- else
- step "Skipping signature verification: cosign ${cosign_ver:-unknown} can't verify this release's bundle format (need cosign >= 2.6)"
- fi
- fi
- }
- download_binary() {
- local version="$1"
- local platform="$2"
- local tmp_dir="$3"
- local url archive_name ext
- # Determine archive extension
- if [[ "$platform" == windows_* ]]; then
- ext="zip"
- else
- ext="tar.gz"
- fi
- archive_name="basecamp_${version}_${platform}.${ext}"
- url="https://github.com/${REPO}/releases/download/v${version}/${archive_name}"
- step "Downloading basecamp v${version} for ${platform}..."
- if ! curl_run -fsSL "$url" -o "${tmp_dir}/${archive_name}"; then
- error "Failed to download from $url${CURL_LAST_ERROR:+ (${CURL_LAST_ERROR})}"
- fi
- # Verify integrity before extraction
- verify_checksums "$version" "$tmp_dir" "$archive_name"
- # Extract binary
- step "Extracting..."
- if [[ "$ext" == "zip" ]]; then
- unzip -q "${tmp_dir}/${archive_name}" -d "$tmp_dir"
- else
- tar -xzf "${tmp_dir}/${archive_name}" -C "$tmp_dir"
- fi
- # Find and install binary
- local binary_name="basecamp"
- if [[ "$platform" == windows_* ]]; then
- binary_name="basecamp.exe"
- fi
- if [[ ! -f "${tmp_dir}/${binary_name}" ]]; then
- error "Binary not found in archive"
- fi
- mkdir -p "$BIN_DIR"
- mv "${tmp_dir}/${binary_name}" "$BIN_DIR/"
- chmod +x "$BIN_DIR/$binary_name"
- info "Installed basecamp to $BIN_DIR/$binary_name"
- }
- setup_path() {
- # Check if BIN_DIR is in PATH
- if [[ ":$PATH:" == *":$BIN_DIR:"* ]]; then
- return 0
- fi
- step "Adding $BIN_DIR to PATH"
- local shell_rc=""
- case "${SHELL:-}" in
- */zsh) shell_rc="$HOME/.zshrc" ;;
- */bash) shell_rc="$HOME/.bashrc" ;;
- *) shell_rc="$HOME/.profile" ;;
- esac
- local path_line="export PATH=\"$BIN_DIR:\$PATH\""
- if [[ -f "$shell_rc" ]] && grep -qF "$BIN_DIR" "$shell_rc" 2>/dev/null; then
- info "PATH already configured in $shell_rc"
- else
- echo "" >> "$shell_rc"
- echo "# Added by basecamp installer" >> "$shell_rc"
- echo "$path_line" >> "$shell_rc"
- info "Added to $shell_rc"
- info "Run: source $shell_rc"
- fi
- }
- verify_install() {
- local platform="$1"
- local binary_name="basecamp"
- if [[ "$platform" == windows_* ]]; then
- binary_name="basecamp.exe"
- fi
- local installed_version err_file
- err_file=$(mktemp)
- if installed_version=$("$BIN_DIR/$binary_name" --version 2>"$err_file"); then
- rm -f "$err_file"
- info "$(green "${installed_version} installed")"
- return 0
- fi
- local run_error
- run_error=$(cat "$err_file")
- rm -f "$err_file"
- local detail="Installation failed - basecamp not working"
- if [[ -n "$run_error" ]]; then
- detail="$detail: $run_error"
- fi
- if [[ "$platform" == windows_* ]]; then
- detail="$detail
- Windows may have blocked the unsigned executable: Smart App Control only runs code-signed binaries.
- Either install inside WSL2 (curl -fsSL https://basecamp.com/install-cli | bash) or see
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 411 on GitHub
- https://github.com/basecamp/basecamp-cli#windows-smart-app-control-and-smartscreen"
- fi
- error "$detail"
- }
- setup_theme() {
- local basecamp_theme_dir="$HOME/.config/basecamp/theme"
- local omarchy_theme_dir="$HOME/.config/omarchy/current/theme"
- # Skip if basecamp theme already configured
- if [[ -e "$basecamp_theme_dir" ]]; then
- return 0
- fi
- # Link to Omarchy theme if available
- if [[ -d "$omarchy_theme_dir" ]]; then
- step "Linking basecamp theme to system theme"
- mkdir -p "$HOME/.config/basecamp"
- ln -s "$omarchy_theme_dir" "$basecamp_theme_dir" || info "Note: Could not link theme (continuing anyway)"
- fi
- }
- show_banner() {
- # Skip braille art if terminal is too narrow (logo 32 + gap 3 + text 8 = 43)
- local cols
- cols=$(tput cols 2>/dev/null || echo 80)
- if [[ "$cols" -ge 44 ]]; then
- local y="" b="" r=""
- if [[ -z "${NO_COLOR:-}" ]] && [[ -t 1 ]]; then
- y=$'\033[38;2;232;162;23m' # brand yellow #e8a217
- b=$'\033[1m' # bold
- r=$'\033[0m' # reset
- fi
- local logo=(
- "⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣤⣶⣶⣶⣶⣶⣶⣦⣤⣀"
- "⠀⠀⠀⠀⠀⠀⠀⢀⣴⣾⣿⣿⣿⠿⠿⠛⠛⠛⠻⠿⣿⣿⣿⣦⣀"
- "⠀⠀⠀⠀⠀⢀⣴⣿⣿⡿⠛⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠙⠻⣿⣿⣦⡀"
- "⠀⠀⠀⠀⣴⣿⣿⡿⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⢿⣿⣿⣄"
- "⠀⠀⢀⣼⣿⣿⠏⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣤⡀⠀⠀⠀⠀⢻⣿⣿⣆"
- "⠀⢀⣾⣿⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣼⣿⣿⠃⠀⠀⠀⠀⠀⢻⣿⣿⡄"
- "⠀⣼⣿⣿⠃⠀⠀⣠⣶⣿⣷⣦⣄⠀⠀⢀⣼⣿⣿⠃⠀⠀⠀⠀⠀⠀⠀⢿⣿⣿⡀"
- "⢸⣿⣿⠇⠀⢠⣾⣿⡿⠛⠻⣿⣿⣷⣤⣾⣿⡿⠃⠀⠀⠀⠀⠀⠀⠀⠀⠘⣿⣿⣇"
- "⠈⠉⠉⠀⢠⣿⣿⡟⠁⠀⠀⠈⠻⣿⣿⣿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢻⣿⣿"
- "⠀⠀⠀⢠⣿⣿⡟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⡇"
- "⠀⠀⠀⢻⣿⣿⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣼⣿⣿⠇"
- "⠀⠀⠀⠀⠙⠿⣿⣿⣷⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣤⣶⣿⣿⡿⠋"
- "⠀⠀⠀⠀⠀⠀⠈⠛⠿⣿⣿⣿⣿⣶⣶⣶⣶⣶⣶⣶⣶⣶⣿⣿⣿⣿⡿⠟⠉"
- "⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠙⠛⠛⠿⠿⠿⠿⠿⠿⠟⠛⠛⠉⠉"
- )
- local text_line=6
- echo ""
- if [[ -t 1 ]] && [[ -z "${NO_COLOR:-}" ]]; then
- # Animated reveal on TTY (skip cursor movement when NO_COLOR is set)
- for line in "${logo[@]}"; do
- echo "${y}${line}${r}"
- sleep 0.03
- done
- # Type "Basecamp" to the right of the logo via cursor repositioning
- sleep 0.1
- local text="Basecamp"
- local lines_up=$(( ${#logo[@]} - text_line ))
- printf "\033[${lines_up}A\033[36G"
- for (( i=0; i<${#text}; i++ )); do
- printf "${b}${text:$i:1}${r}"
- sleep 0.03
- done
- printf "\033[${lines_up}B\r"
- else
- # Static output when piped — no sleeps, no cursor movement
- for i in "${!logo[@]}"; do
- if [[ "$i" -eq "$text_line" ]]; then
- echo "${logo[$i]} Basecamp"
- else
- echo "${logo[$i]}"
- fi
- done
- fi
- echo ""
- else
- echo ""
- echo "Basecamp CLI"
- echo ""
- fi
- }
- main() {
- show_banner
- # Check for curl
- if ! command -v curl &>/dev/null; then
- error "curl is required but not installed"
- fi
- local platform version tmp_dir
- platform=$(detect_platform)
- detect_curl_fallback
- if [[ -z "$BIN_DIR" ]]; then
- BIN_DIR=$(default_bin_dir "$platform")
- fi
- if [[ -n "$VERSION" ]]; then
- version="$VERSION"
- if [[ ! $version =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
- error "Invalid version '${version}'. Expected semver format (e.g. 1.2.3 or 1.2.3-rc.1)."
- fi
- else
- version=$(get_latest_version)
- fi
- tmp_dir=$(mktemp -d)
- trap "rm -rf '${tmp_dir}'" EXIT
- local binary_name="basecamp"
- if [[ "$platform" == windows_* ]]; then
- binary_name="basecamp.exe"
- fi
- download_binary "$version" "$platform" "$tmp_dir"
- setup_path
- setup_theme
- verify_install "$platform"
- echo ""
- # Run first-time setup when a controlling terminal can handle OAuth approval.
- # Non-interactive environments (CI, redirected output, coding agents like Claude
- # Code or Codex) get the baseline skill installed, a best-effort agent connection
- # via `setup agents`, and next-step instructions instead.
- if [[ "${BASECAMP_SKIP_SETUP:-}" == "1" ]]; then
- step "Skipping first-time setup (BASECAMP_SKIP_SETUP=1)"
- post_install_setup "$binary_name"
- echo ""
- echo " Next steps:"
- echo " $(bold "basecamp auth login") Authenticate with Basecamp"
- echo " $(bold "basecamp setup") Run first-time setup"
- echo ""
- elif can_run_first_time_setup; then
- # The canonical `curl ... | bash` install owns stdin while Bash reads the
- # script. Give setup the controlling terminal so OAuth can complete.
- run_first_time_setup "$BIN_DIR/$binary_name" </dev/tty
- else
- if env_value_is_true "${BASECAMP_NONINTERACTIVE:-}"; then
- info "Skipping first-time setup (BASECAMP_NONINTERACTIVE enabled)."
- else
- info "Skipping first-time setup (no usable terminal detected)."
- fi
- post_install_setup "$binary_name"
- echo ""
- echo " Next steps:"
- echo " $(bold "basecamp auth login") Authenticate with Basecamp"
- echo " $(bold "basecamp setup") Run first-time setup"
- echo ""
- fi
- }
- # binary_supports_setup_agents reports whether the installed binary exposes the
- # `setup agents` subcommand (added after v0.7.2). The hosted install.sh from main
- # can outrun the latest release, so we probe rather than assume.
- binary_supports_setup_agents() {
- "$1" setup --help 2>/dev/null | grep -qE '^[[:space:]]+agents[[:space:]]'
- }
- # binary_supports_setup_agent reports whether the binary exposes a per-agent
- # `setup <id>` subcommand for the given agent id (claude, codex or grok).
- binary_supports_setup_agent() {
- "$1" setup --help 2>/dev/null | grep -qE "^[[:space:]]+$2[[:space:]]"
- }
- # post_install_setup installs the baseline skill and connects coding agents
- # without prompting. It honors BASECAMP_SETUP_AGENT (claude|codex|grok|all|none;
- # unset = auto-detect). Never runs the interactive wizard.
- #
- # Cross-version: newer binaries get the intent-neutral `setup agents`. Older
- # release binaries (no `setup agents`) fall back WITHOUT reintroducing the
- # Claude-first bug — only an *explicitly* selected agent is connected. `all`
- # runs every per-agent setup the binary supports; an unset, auto, or ambiguous
- # selector installs the shared skill only (`skill install`).
- #
- # Every real invocation carries BASECAMP_NO_KEYRING=1, per-command rather than
- # exported: these calls never touch credentials, but release binaries up to
- # v0.7.2 probe the OS keyring on startup for every command, and on a locked
- # headless keychain (CI, ssh) that probe blocks forever. The `setup --help`
- # capability probes stay bare — help short-circuits before the probe.
- post_install_setup() {
- local binary_name="$1"
- local bin="$BIN_DIR/$binary_name"
- if binary_supports_setup_agents "$bin"; then
- BASECAMP_NO_KEYRING=1 "$bin" setup agents || true
- return 0
- fi
- case "${BASECAMP_SETUP_AGENT:-}" in
- claude|codex|grok)
- # Capability-check first: an old `setup` parent accepts an unadvertised
- # agent id as a stray positional arg and launches the INTERACTIVE wizard,
- # violating the non-interactive contract. Degrade to the shared skill.
- if binary_supports_setup_agent "$bin" "${BASECAMP_SETUP_AGENT}"; then
- BASECAMP_NO_KEYRING=1 "$bin" setup "${BASECAMP_SETUP_AGENT}" || true
- else
- BASECAMP_NO_KEYRING=1 "$bin" skill install || true
- fi
- ;;
- all)
- # Explicit "every agent": dispatch each per-agent setup the binary knows,
- # falling back to the shared skill if it supports none of them.
- local ran_agent=0 agent
- for agent in claude codex grok; do
- if binary_supports_setup_agent "$bin" "$agent"; then
- BASECAMP_NO_KEYRING=1 "$bin" setup "$agent" || true
- ran_agent=1
- fi
- done
- [[ "$ran_agent" -eq 1 ]] || BASECAMP_NO_KEYRING=1 "$bin" skill install || true
- ;;
- *)
- # Intent-neutral on old binaries: install the shared skill, never pick an
- # agent. The user connects one via the printed "Next steps".
- BASECAMP_NO_KEYRING=1 "$bin" skill install || true
- ;;
- esac
- }
- # Guard so sourcing the script (e.g. from tests) doesn't run the installer.
- # The if-form is required: `[[ … ]] && main` returns 1 when sourced, which
- # trips `set -e` in the sourcing shell. The `:-$0` fallback is also
- # required: bash executing from stdin (curl | bash) or -c leaves BASH_SOURCE
- # unset, and the bare expansion aborts under `set -u` (#568).
- if [[ "${BASH_SOURCE[0]:-$0}" == "$0" ]]; then
- main "$@"
- fi
scripts/stage-installer-ps1.sh · Bundled script · 57 lines · 1 finding marked
- #!/usr/bin/env sh
- # Usage: scripts/stage-installer-ps1.sh SOURCE DEST
- #
- # Stage a copy of the PowerShell installer for Authenticode signing, in the
- # only shape where jsign's digest and PowerShell's agree.
- #
- # jsign computes the script digest as UTF-16LE of the file content with the
- # signature block stripped, and applies NO line-ending normalization
- # (SignableScript.computeDigest). PowerShell's script SIP normalizes to CRLF
- # before hashing. Sign an LF file and the two digests differ, so
- # Get-AuthenticodeSignature reports HashMismatch and the installer is refused
- # under AllSigned/RemoteSigned. That is what shipped in v0.8.0-rc.2.
- #
- # Two invariants make the digests agree:
- #
- # CRLF removes the normalization disagreement above.
- #
- # pure ASCII removes an encoding disagreement that CRLF alone would not
- # fix. The file has no BOM; jsign assumes UTF-8, but Windows
- # PowerShell 5.1 assumes ANSI (Windows-1252) for BOM-less files.
- # Any byte above 0x7F therefore decodes to different characters
- # on each side and the digests diverge again. Within ASCII the
- # two encodings are identical byte-for-byte, so the question
- # never arises. Adding a BOM would be the other way out, but it
- # trades a known-good invariant for jsign's
- # isByteOrderMarkSigned() matching Microsoft's undocumented
- # treatment of the BOM in the hash — untestable without a
- # signing round-trip.
- #
- # The source file is left alone: raw-main install.ps1 stays LF and unsigned,
- # which is the `irm | iex` path and needs neither.
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 31 on GitHub
- set -eu
- SRC="${1:?usage: stage-installer-ps1.sh SOURCE DEST}"
- DEST="${2:?usage: stage-installer-ps1.sh SOURCE DEST}"
- [ -f "$SRC" ] || { echo "stage-installer-ps1: source not found: $SRC" >&2; exit 1; }
- # Reject non-ASCII before signing rather than after. Under LC_ALL=C every byte
- # above 0x7F is non-printable, so this matches exactly the bytes that would
- # make jsign and PowerShell 5.1 disagree.
- if LC_ALL=C grep -n '[^[:print:][:space:]]' "$SRC" >/dev/null 2>&1; then
- echo "stage-installer-ps1: $SRC contains non-ASCII bytes, which would produce" >&2
- echo " a signature PowerShell 5.1 rejects as HashMismatch (it decodes BOM-less" >&2
- echo " files as Windows-1252 while jsign assumes UTF-8). Offending lines:" >&2
- LC_ALL=C grep -n '[^[:print:][:space:]]' "$SRC" >&2
- exit 1
- fi
- mkdir -p "$(dirname "$DEST")"
- # LF -> CRLF, idempotent: strip any existing CR first so a CRLF source does
- # not become CR CR LF.
- awk '{ sub(/\r$/, ""); printf "%s\r\n", $0 }' "$SRC" > "$DEST"
- echo "stage-installer-ps1: staged $DEST (pure ASCII, CRLF)"
Version history
v0.30.011/14/2026
v0.29.011/13/2026
v0.27.011/11/2026
v0.25.011/9/2026
v0.24.311/8/2026
v0.24.011/7/2026
v0.22.111/2/2026
v0.22.010/31/2026
v0.21.010/29/2026
v0.20.010/28/2026
v0.19.010/27/2026
v0.18.110/25/2026
v0.17.010/23/2026
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.