Terminal
Terminal/Skill
Lets an agent work in Basecamp through its CLI: projects, todos, cards, messages, files, schedules and search.
By 37signals (Basecamp)
Works with
npx skills add basecamp/skills --skill basecampUse the installed CLI as the command reference. This skill defines the operating rules; it intentionally does not duplicate the CLI's command catalog.
For each task:
Infer the deepest plausible leaf command from the user's words.
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
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
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.
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.
~/.config/basecamp/credentials.json.jq. Use the CLI's built-in --jq.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 show or comments thread to get
reply_target when context matters..basecamp/config.json before assuming a
project; otherwise pass --in <project> or the scope shown by leaf help.Choose deliberately:
| Goal | Mode |
|---|---|
| Extract, count, or transform data | --jq '<expression>' |
| Consume full structured response | --json |
| Consume data without an envelope | --agent |
| Present portable output directly to a person | --md |
--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}]'
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.
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.
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.
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.
Structured failures include error, code, retryable, and often hint.
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.basecamp doctor --json and
basecamp auth status --json before changing credentials.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.
Before changing Basecamp:
For destructive or broad operations, preview when the command offers a dry-run and do not expand the user's requested scope.