basecamp

What this skill does

# /basecamp - Basecamp Workflow Command

Full CLI coverage: 155 endpoints across todos, cards, messages, files, schedule, check-ins, timeline, recordings, templates, webhooks, subscriptions, lineup, chat, gauges, assignments, notifications, and accounts.

## Agent Invariants

**MUST follow these rules:**

1. **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.**
2. **Parse URLs first** with `basecamp url parse "<url>"` to extract IDs
3. **Comments are flat** - reply to parent recording, not to comments
4. **Check context** via `.basecamp/config.json` before assuming project
5. **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) 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.
6. **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.

### 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}` |
| 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.

**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:

```bash
basecamp todos --agent --help
```

```json
{"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 include `notes` with domain-specific agent hints (e.g., "Cards do NOT support --assignee filtering").

### Pagination

```bash
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
- Project from `.basecamp/config.json` if `--in` not specified

## 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`.

| 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 recordings todos --json` (no assignee data — cannot filter by person) |
| Overdue todos (in project) | `basecamp todos list --overdue --in <project> --json` |
| Overdue todos (cross-project) | `basecamp reports overdue --json` |
| Assign todo | `basecamp assign <id> [id...] --to <person> --in <project> --json` |
| Assign card | `basecamp assign <id> [id...] --card --to <person> --in <project> --json` |
| Assign card step | `basecamp assign <id> [id...] --step --to <person> --in <project> --json` |
| Create todo | `basecamp todo "Task" --in <project> --list <list> --json` |
| Create todolist | `basecamp todolists create "Name" --in <project> --json` |
| Complete todo | `basecamp done <id> --json` |
| List cards | `basecamp cards list --in <project> --json` |
| Create card | `basecamp card "Title" --in <project> --json` |
| Move card | `basecamp cards move <id> --to <column> [--position N] --in <project> --json` |
| Move card to on-hold | `basecamp cards move <id> --on-hold --in <project> --json` |
| Post message | `basecamp message "Title" "Body" --in <project> --json` |
| Post with @mention | `basecamp message "Title" "Hey @First.Last, ..." --in <project> --json` |
| Post silently | `basecamp message "Title" "Body" --no-subscribe --in <project> --json` |
| Post to chat | `basecamp chat post "Message" --in <project> --json` |
| Add comment | `basecamp comment <recording_id> "Text" --in <project> --json` |
| List attachments | `basecamp attachments list <id\|url> --json` |
| Download attachments | `basecamp attachments download <id> --out /tmp/` |
| Show + download | `basecamp todos show <id> --download-attachments --json` |
| Stream attachment to stdout | `basecamp attachments download <id> --file <name> --out -` |
| Search | `basecamp search "query" --json` |
| Parse URL | `basecamp url parse "<url>" --json` |
| Upload file | `basecamp files uploads create <file> [--vault <folder_id>] --in <project> --json` |
| Download file | `basecamp files download <id> --in <project>` |
| Stream file to stdout | `basecamp files download <id> --out - --in <project>` |
| Download storage URL | `basecamp files download "https://storage.3.basecamp.com/.../download/report.pdf"` |
| My assignments | `basecamp assignments --json` (priorities + non-priorities) |
| Overdue assignments | `basecamp assignments due overdue --json` |
| Completed assignments | `basecamp assignments completed --json` |
| Notifications | `basecamp notifications --json` |
| Mark notification read | `basecamp notifications read <id> --json` |
| Gauges (account-wide) | `basecamp gauges list --json` |
| Gauge needles | `basecamp gauges needles --in <project> --json` |
| Create needle | `basecamp gauges create --position 75 --color green --in <project> --json` |
| Account details | `basecamp accounts show --json` |
| Watch timeline