basecamp

name basecamp description Interact with Basecamp via the Basecamp CLI. Full API coverage: projects, todos, cards, messages, files, schedule, check-ins, timeline, recordings, templates, webhooks, subscriptions, lineup, chat, pings, gauges, assignments, notifications, bookmarks, bubble-up, drafts, notes, calendars, and accounts. Use for ANY Basecamp question or action. triggers ["basecamp","/basecamp","basecamp todos","basecamp project","basecamp cards","basecamp chat","basecamp campfire","basecamp messages","basecamp file","basecamp document","basecamp bookmarks","basecamp bubble-up","basecamp drafts","basecamp notes","basecamp calendars","basecamp schedule","basecamp checkin","basecamp check-in","basecamp timeline","basecamp template","basecamp webhook","basecamp gauge","basecamp assignment","basecamp notification","basecamp account","link to basecamp","track in basecamp","post to basecamp","comment on basecamp","complete todo","mark done","create todo","[Truncated]"] invocable true argument-hint [action] [args...] /basecamp - Basecamp Workflow Command Full CLI coverage: 189 tracked in-scope endpoints across todos, cards, messages, files, schedule, check-ins, timeline, recordings, templates, webhooks, subscriptions, lineup, chat, pings, gauges, assignments, notifications, and accounts. Agent Invariants MUST follow these rules: Choose the right output mode — --jq when you need to filter/extract data; --json for full JSON; --md when presenting results to a human (see Output Modes below). Never pipe to external jq — use --jq instead. Parse URLs first with basecamp url parse "<url>" to extract IDs Comments are flat - reply to parent recording, not to comments Check context via .basecamp/config.json before assuming project Content fields accept Markdown and @mentions — message body and comment content accept Markdown syntax; the CLI converts to HTML automatically. Use Markdown formatting (lists, bold, links, code blocks, tables) for rich content. Four mention syntaxes are available (prefer deterministic for agents): [@Name](mention:SGID) — zero API calls, embeds SGID directly (preferred for agents) [@Name](person:ID) — one API call, resolves person ID to SGID via pingable set @sgid:VALUE — inline SGID embed for pipeline composability @Name / @First.Last — fuzzy name resolution (may be ambiguous) For todos, documents, and cards, content is sent as-is — use plain text or HTML directly. Table boundary: GFM tables round-trip: they render in message/comment bodies, display converts them back to pipe tables, and the TUI in-place editors open simple grids for editing. Only complex tables — merged cells (colspan/rowspan), captions, extra header rows, nested tables, attachments/images or block content inside cells, multi-paragraph or multi-line cells, or a table inside a blockquote or list — refuse to open, since a GFM pipe table can't represent those shapes (edit them on Basecamp web, or replace the whole field via messages update / comments update / todos update --description , which take fresh content and are unaffected). Complex tables still display best-effort, flattened to a plain grid. Multiline / non-ASCII content: do not rely on bash ANSI-C quoting ( $'...\n...' ) — it is a bash/zsh extension. Under a POSIX /bin/sh (dash, busybox-ash, common in sandboxes) the $ is passed through literally and posts a stray leading $ , and \n stays a literal backslash-n. Pipe the content via stdin instead, using - as the content argument: printf '%s\n' '海报 mockup 方向稿：' '' '<bc-attachment ...>' | basecamp comments create <recording_id> - -- in <project> --json - means "read from stdin" on every content input: content-kind positionals ( comments create/update , messages create [body] , cards create [body] , todos create , docs documents create [content] , chat post/update , boost create , checkins answer create/update , notes set ) and content flags ( --data on api post/put , --body , --content , --description , --comment on todos sweep , --file on notes set ). Each command's --agent help lists its stdin inputs. Rules: A pipe is never consumed implicitly — without - it is ignored (or, where content is required and missing, the error teaches - ). Only one input can read stdin per invocation. A literal - anywhere else (a title, a name, a path) errors when stdin is piped . Escape a positional after the -- separator ( basecamp projects create -- - ); a flag value has no in-line escape — run the command without piped stdin. basecamp help and shell completion are exempt: they write nothing to Basecamp, and completion legitimately receives - as the word being completed. - with nothing piped (interactive TTY) errors immediately instead of hanging; use a pipe, a heredoc ( basecamp comments create <id> - <<'EOF' ), or --edit where offered. Trailing newlines are trimmed from stdin content, so printf 'x\n' | ... - posts x (this keeps boost create - inside its 16-rune limit). Universal - support (and the stray- - guard) shipped in v0.10.0 . Older CLIs do not support it consistently: comments create/update read stdin, while unsupported inputs may treat - as literal content or fail. For example, messages create "Title" - posts a body of - , which Markdown renders as an empty bullet list. When the CLI version is unknown, check basecamp --version first, or pass the content portably as "$(cat file.md)" and verify the posted content when it matters. Project scope is mandatory for most commands — via --in <project> or .basecamp/config.json . Cross-project exceptions: basecamp reports assigned for assigned work, basecamp assignments for structured assignment views, basecamp reports overdue for overdue todos, basecamp reports schedule for upcoming schedule across all projects, basecamp recordings <type> for browsing by type, basecamp notifications for notifications, basecamp gauges list for account-wide gauges, and the seven list commands covered in item 7. Account-wide listing. basecamp todos list --all-projects --json lists across every project; the same flag does the same on cards list , messages list , comments list , files list , forwards list , and checkins answers . It overrides a configured project, and with no project in scope those commands already list account-wide rather than prompting. Flags that name something inside a single project are rejected there rather than silently ignored. Account-wide listings return the first 100 items by default — account-wide "all" is the whole account, not one project's worth. Use --limit N to raise the cap (it walks pages until N are collected) or --all for everything. --page N fetches exactly one page, but only on the paginated listings. The two overdue variants — basecamp todos list --all-projects --overdue and basecamp cards list --all-projects --overdue — come from unpaginated endpoints. They accept --limit and --all but reject --page , so do not generate --page against them. Output Modes Choosing a mode: Goal Flag Format Filter/extract JSON data --jq '<expr>' Built-in jq filter (no external jq needed). Implies --json ; filter runs on the envelope. Filter in agent mode --agent --jq '<expr>' Filter runs on data-only payload (no envelope), matching --agent contract. Full JSON output --json JSON envelope: {ok, data, summary, breadcrumbs, meta} ; errors: {ok:false, error, code, retryable, hint, meta} Show results to a user --md / -m GFM tables, task lists, structured Markdown Automation / scripting --agent Success: raw JSON data (no envelope); errors: {ok:false,...} object; no interactive prompts Always pass --json or --md explicitly — auto-detection depends on config and may not produce the format you expect. Use --md when composing reports, summarizing data, or displaying results inline. --agent is for headless integration scripts. Avoiding interactive prompts. The flags --agent / --json / --quiet / --ids-only / --count and the environment variable BASECAMP_NONINTERACTIVE=1 suppress interactive selection prompts. --md does not — if a required target is ambiguous (e.g. a project with multiple todosets and no --todoset ), and the CLI is attached to a terminal, it will show a blocking picker. When you need Markdown output and no prompts, either pass the flag that names whatever is ambiguous ( --todoset <id> for the todoset case above, or --in <project> / --list <id> when the project or list is ambiguous) or set BASECAMP_NONINTERACTIVE=1 in the environment. BASECAMP_NONINTERACTIVE disables all prompts (they become actionable errors instead) without changing the output format — an escape hatch for agents running under a PTY. Other modes: --quiet (success: raw JSON, no envelope; errors: {ok:false,...} ), --ids-only , --count , --stats (session statistics), --styled (force ANSI), -v / -vv (verbose/trace), --jq '<expr>' (built-in jq filter — see below). CLI Introspection Navigate unfamiliar commands with --agent --help — returns structured JSON describing any command: basecamp todos --agent -- help { "command" : "todos" , "path" : "basecamp todos" , "short" : "..." , "long" : "..." , "usage" : "..." , "notes" : [ "..." ] , "subcommands" : [ { "name" : "sweep" , "short" : "..." , "path" : "basecamp todos sweep" } ] , "flags" : [ { "name" : "assignee" , "type" : "string" , "default" : "" , "usage" : "..." } ] , "inherited_flags" : [ { "name" : "json" , "shorthand" : "j" , "type" : "bool" , "default" : "false" , "usage" : "..." } ] } Walk the tree: start at basecamp --agent --help for top-level commands, then drill into any subcommand. Commands carry domain-specific agent hints (e.g., " --assignee filters the account-wide listing only; within a project, fetch all and filter client-side"). Pagination basecamp <cmd> -- limit 50 # Cap results (default varies by resource) basecamp <cmd> --all # Fetch all (may be slow for large datasets) basecamp <cmd> --page 1 # First page only, no auto-pagination --all and --limit are mutually exclusive. --page cannot combine with either. Smart Defaults --assignee me resolves to current user --due tomorrow / --due +3 / --due "next week" — natural date parsing, when setting a due date ( todos create , todos update , cards create , and so on) --due on a listing is a different flag and does not take dates: it accepts only with , without , or overdue , and only account-wide. basecamp todos list --due tomorrow is rejected. For date-based listing use --overdue , --no-due-date , or basecamp assignments due <scope> Project from .basecamp/config.json if --in not specified Multiple identities use named profiles: basecamp profile create <name> , then select one with global --profile <name> or BASECAMP_PROFILE=<name> . Quick Reference Note: Most queries require project scope (via --in <project> or .basecamp/config.json ). Cross-project exceptions: basecamp reports assigned , basecamp assignments , basecamp reports overdue , basecamp reports schedule , basecamp recordings <type> , basecamp notifications , basecamp gauges list . Seven list commands also list account-wide: basecamp todos list --all-projects --json , and likewise cards list , messages list , comments list , files list , forwards list , and checkins answers . Task Command List projects basecamp projects list --json My todos (in project) basecamp todos list --assignee me --in <project> --json My todos (cross-project) basecamp reports assigned --json (defaults to "me") My schedule (cross-project) basecamp reports schedule --json (upcoming events across all projects) All todos (cross-project) basecamp todos list --all-projects --json (grouped by project) Overdue todos (in project) basecamp todos list --overdue --in <project> --json Overdue todos (cross-project) basecamp todos list --all-projects --overdue --json (flat, oldest first) or basecamp reports overdue --json (bucketed by lateness) All cards (cross-project) basecamp cards list --all-projects --json (grouped by project) Someone's todos (cross-project) basecamp todos list --all-projects --assignee "Ann" --json (server-side filter) Two people's todos (cross-project) basecamp todos list --all-projects --assignee ann --assignee bob --json (matches either) Someone's cards (cross-project) basecamp cards list --all-projects --assignee "Ann" --json Todos with no due date set (cross-project) basecamp todos list --all-projects --due without --json My bookmarks basecamp bookmarks list --json Bookmark something basecamp bookmarks add <id-or-url> --json Is it bookmarked? basecamp bookmarks check <id-or-url> --json (always exits 0) Bubble a recording up basecamp bubble-up add <id-or-url> --json Schedule a bubble-up basecamp bubble-up add <id-or-url> --at tomorrow --json Pop a bubble-up basecamp bubble-up remove <id-or-url> --json My unpublished drafts basecamp drafts list --json Read my personal note basecamp notes show --json Replace my personal note basecamp notes set "<content>" --json Check-ins I owe answers to basecamp checkins reminders --json Add to Up Next basecamp assignments prioritize <id> --json Recolor a calendar basecamp calendars update <id-or-url> --color blue --json Todo outside any list basecamp todos create "<content>" --loose --in <project> --json