Basecamp CLI

Use the installed CLI as the command reference. This skill defines the operating rules; it intentionally does not duplicate the CLI's command catalog.

Discovery-first workflow

For each task:

1. Infer the deepest plausible leaf command from the user's words.
2. If its exact arguments or flags are not already established by a tool result

in this conversation, inspect that leaf directly:

   basecamp <group> <subcommand> --agent --help

1. If the leaf does not exist, inspect its nearest parent group. Use root help

only when the top-level group itself is unclear:

   basecamp <group> --agent --help   # fallback
   basecamp --agent --help           # last resort

1. Treat leaf usage, args, flags, and notes as the source of truth. Do

not guess positional arguments, flags, aliases, scope, or whether a group runs bare.

1. Execute with an explicit output mode, then read structured errors and

breadcrumbs before deciding what to do next.

Targeted leaf help is cheap and local; root help returns the full command catalog and is not token-cheap. Do not load root help merely to confirm global flags already documented by this skill. For obvious Docs & Files requests, route straight to files list, files download, or files uploads create before trying parent or root help. A subcommand's inherited_flags is intentionally short; global flags such as --agent, --jq, --profile, and --verbose still apply where supported.

Non-negotiable rules

• Never read, print, or log OAuth tokens or credential files. In particular, do

not open ~/.config/basecamp/credentials.json.

• Never pipe JSON to an external jq. Use the CLI's built-in --jq.
• Parse a supplied Basecamp URL before using IDs from it:

basecamp url parse "<url>" --json. Only trust URLs from a known Basecamp host. Read-only commands whose leaf help explicitly accepts <id|url> may consume the trusted URL directly.

• Comments are flat. A reply is posted to the parent recording, never to a

comment ID. For a comment URL, use comments show or comments thread to get reply_target when context matters.

• Respect project context. Check .basecamp/config.json before assuming a

project; otherwise pass --in <project> or the scope shown by leaf help.

• Use non-interactive output for agent work. Do not allow an ambiguous picker to

block execution.

• When a result reports content or description attachments, download and inspect

them. Images often contain the essential task context.

• Follow the installed command's help over examples remembered from earlier CLI

versions.

Output modes

Choose deliberately:

--jq implies JSON. It normally filters the JSON envelope, so data is commonly under .data. With --agent --jq, it filters the data-only payload. Use --md for human-facing listings, but remember that --md alone does not suppress interactive prompts. Add enough scope to remove ambiguity or set BASECAMP_NONINTERACTIVE=1.

Examples of generic transformations, not command discovery:

basecamp <leaf-command> --jq '.data | length'
basecamp <leaf-command> --jq '[.data[] | {id, name}]'

Project, account, and pagination scope

Do not infer that a command is project-scoped or account-wide from its noun. Inspect the leaf help and its notes. Use the user's explicit project/account when provided; otherwise honor trusted local configuration.

For paginated commands, inspect help before combining pagination flags. In general, --limit N caps an auto-paginated result, --all walks every page, and --page N requests one page, but individual endpoints can differ and mutually exclusive combinations are rejected.

Named identities use profiles. Select one with global --profile <name> or BASECAMP_PROFILE=<name>; do not silently switch profiles or default accounts.

URLs and replies

A parsed URL can supply account_id, project_id, recording_id, and, when a fragment points at a comment, comment_id.

basecamp url parse "https://3.basecamp.com/123/buckets/456/todos/789" --json

For replies, fetch reply-ready context rather than posting to the fragment ID:

basecamp comments thread "<comment-url>" --json
# Post to .data.reply_target.recording_id

Use comments show when only the cheap reply target and mention atoms are needed; use comments thread when surrounding discussion matters.

Pings

A ping is a private conversation between people on an account, outside any project: direct with one other person, a group with more. It is not a project chat, so chat list --all never shows one. Use the pings group.

basecamp pings list --agent                  # your pings
basecamp pings start "Jane Smith" --agent    # open your ping with Jane, or start it
basecamp pings post "Jane Smith" "Lunch?" --agent
basecamp pings messages "Jane Smith" --agent

• A <ping> is a ping ID, a ping URL (/circles/<id> or /circles/<id>@<line>),

or a person. A bare number is always a ping ID, never a person ID.

• pings list shows a ping once it has a message. A ping you just started is

not listed yet; pings start prints it.

• pings start reuses what exists: one direct ping per person, and a group per

set of people unless --new-group. Use it to find the ping you already have.

• pings messages and pings show of a person read the direct ping you already

have and never start one; pings post and pings upload start it if missing.

• @mentions in pings post resolve among the people in that ping.
• A message URL (/circles/<id>@<line>) works with basecamp show and

chat line; edit or delete such a message with chat update or chat delete on that URL.

Spotlights

A spotlight puts a recording's card in the Spotlights area of its project's home page. It is not a pin: messages pin only keeps a message at the top of its Message Board. spotlight is a top-level command, outside every recording type's group, and takes the ID or URL of a message, document, file, to-do list, to-do, card, card column, check-in question, schedule entry and more. unspotlight removes it, as "Remove Spotlight" does in Basecamp.

basecamp spotlight <id|url> --agent
basecamp unspotlight <id|url> --agent

Project wallpaper

The wallpaper is the image behind a project's pages. The projects wallpaper group sets, lays out, and removes it, for the project in --in/--project or the configured default:

basecamp projects wallpaper set skyline.jpg --mode tile --in "<project>" --json
basecamp projects wallpaper mode fill --in "<project>" --json
basecamp projects wallpaper remove --in "<project>" --json

• People and personal assistants follow project-edit permissions. Shared

agents are refused (403); do not retry or route around that refusal.

• The CLI checks the file's size and MIME hint before uploading; leaf help

names the limits. Server image validations still apply. --mode is fill or tile, and leaving it out keeps the current mode.

• Each command returns the project. .data.wallpaper is {url, mode}, and is

absent when the project has none; projects show carries the same field. The URL requires authentication and redirects to the image; it is not a public image link.

Content and stdin

Command help declares content arguments and stdin support. Titles are generally plain text; rich-text fields generally accept Markdown and can opt into HTML with --format html where documented. Do not guess a --title, --body, or --content flag when help shows a positional argument.

For multiline, non-ASCII, or shell-sensitive content, pass - in the documented content position and pipe stdin:

printf '%s\n' 'First line' '' 'Second line' |
  basecamp <leaf-command> <other-args> - --json

A pipe is never consumed implicitly. Only one input may read stdin in an invocation. Do not use shell-specific ANSI-C quoting such as $'line 1\nline 2' in portable commands.

Rich-text fields support Mermaid diagrams. Put the source in a fenced code block with the language mermaid, and Basecamp shows the diagram to people reading the post. Previews, emails, and exports show the source, and so does a post whose source does not parse. Use a diagram for a flow, sequence, timeline, or structure that is easier to follow as a picture than as prose. Diagram source spans several lines, so pass it on stdin:

basecamp messages create "Release flow" - --in "<project>" --json <<'EOF'
How a release reaches production:

flowchart LR Merge --> CI --> Staging --> Production

EOF

To embed a video, a Dash chart, or anything else Basecamp's editor embeds when a link is pasted, put the URL on a line by itself in Markdown content. The CLI asks Basecamp for the embed and waits for it. A URL Basecamp can't embed stays a link, and so does a URL inside a sentence, a list, a quote, or code. To keep a link to something Basecamp could embed, write [title](url).

basecamp cards create "Checkout latency" - --in "<project>" --json <<'EOF'
p99 since the deploy:

https://dash.37signals.com/widgets/abc
EOF

With --format html nothing is embedded for you: run basecamp embeds create <url> --json and put its attachment tag in the HTML.

For deterministic mentions, prefer the machine-provided mention syntax from people or comment results, for example [@Name](mention:SGID). Mention support varies by field; leaf help is authoritative.

Errors and recovery

Structured failures include error, code, retryable, and often hint.

• Retry only when retryable is true, with bounded backoff.
• retryable: false means there is no positive retry signal; it covers both

known verdicts and unclassified failures. Inspect code, error, and hint before choosing recovery, and do not blindly repeat the same call.

• For usage errors, inspect leaf help and supply the named positional argument.
• If the CLI rejects a command or flag as unknown, check the group's help for

its current form first. If this skill names it and the help lacks it, the CLI and this skill may come from different releases: basecamp doctor --json reports both versions. Name the older side to the user: basecamp upgrade for the CLI, or updating the plugin.

• For ambiguous names, use an ID or add the missing project/container scope.
• For auth or connectivity diagnosis, use basecamp doctor --json and

basecamp auth status --json before changing credentials.

• Before any login recovery, inspect oauth_type. An agent profile must be

recovered with the agent/client-credentials flow named by the CLI hint; a normal person login can replace the agent identity.

Do not improvise raw API calls merely because a command failed. First inspect the relevant help and error hint. Use basecamp api only when the CLI has no native operation and the API path and payload are known.

Mutations

Before changing Basecamp:

1. Resolve the account, project, container, and item unambiguously.
2. Inspect leaf help for required positional arguments and visibility or

notification behavior.

1. Make the smallest requested change.
2. Return the resulting ID/URL and summarize what changed.

For destructive or broad operations, preview when the command offers a dry-run and do not expand the user's requested scope.