mirror of
https://github.com/basecamp/skills.git
synced 2026-09-14 20:16:48 +08:00
Sync skills from basecamp-cli v0.4.0
Source: basecamp/basecamp-cli@ee9d20a6b1
This commit is contained in:
basecamp-cli[bot]
+200
-102
@@ -69,24 +69,44 @@ Full CLI coverage: 130 endpoints across todos, cards, messages, files, schedule,
|
||||
|
||||
**MUST follow these rules:**
|
||||
|
||||
1. **Always use `--json`** for structured, predictable output
|
||||
1. **Choose the right output mode** — `--json` when you need to parse data; `--md` when presenting results to a human (see Output Modes below)
|
||||
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. **Rich text fields accept Markdown** - the CLI converts to HTML automatically
|
||||
6. **Project scope is mandatory** — via `--in <project>` or `.basecamp/config.json`. There is no cross-project query mode. For cross-project data, use `basecamp recordings <type>` or loop through projects individually.
|
||||
5. **Content fields accept Markdown** — 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. 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 reports overdue` for overdue todos, `basecamp recordings <type>` for browsing by type.
|
||||
|
||||
### Output Modes
|
||||
|
||||
**Choosing a mode:**
|
||||
|
||||
| Goal | Flag | Format |
|
||||
|------|------|--------|
|
||||
| Parse data, pipe to jq | `--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).
|
||||
|
||||
### CLI Introspection
|
||||
|
||||
Navigate unfamiliar commands with `--agent --help` — returns structured JSON describing any command:
|
||||
|
||||
```bash
|
||||
basecamp <cmd> --json # JSON envelope with data, summary, breadcrumbs (recommended)
|
||||
basecamp <cmd> --quiet # Raw JSON data only, no envelope
|
||||
basecamp <cmd> --agent # Machine-readable, no interactive prompts
|
||||
basecamp <cmd> --ids-only # Just IDs, one per line
|
||||
basecamp <cmd> --count # Just the count
|
||||
basecamp <cmd> --stats # Include session stats in output
|
||||
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
|
||||
@@ -105,23 +125,27 @@ basecamp <cmd> --page 1 # First page only, no auto-pagination
|
||||
|
||||
## Quick Reference
|
||||
|
||||
> **Note:** Most queries require project scope (via `--in <project>` or `.basecamp/config.json`). For cross-project data, use `basecamp recordings <type>` or loop through projects individually.
|
||||
> **Note:** Most queries require project scope (via `--in <project>` or `.basecamp/config.json`). Cross-project exceptions: `basecamp reports assigned`, `basecamp reports overdue`, `basecamp recordings <type>`.
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| List projects | `basecamp projects --json` |
|
||||
| My todos (in project) | `basecamp todos --assignee me --in <project> --json` |
|
||||
| All todos (cross-project) | `basecamp recordings todos --json` (filter client-side) |
|
||||
| Overdue todos | `basecamp todos --overdue --in <project> --json` |
|
||||
| Create todo | `basecamp todo --content "Task" --in <project> --list <list> --json` |
|
||||
| Create todolist | `basecamp todolists create --name "Name" --in <project> --json` |
|
||||
| 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") |
|
||||
| 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> --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 --in <project> --json` |
|
||||
| Create card | `basecamp card --title "Title" --in <project> --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> --in <project> --json` |
|
||||
| Post message | `basecamp message --subject "Title" --content "Body" --in <project> --json` |
|
||||
| Post to campfire | `basecamp campfire post --content "Message" --in <project> --json` |
|
||||
| Add comment | `basecamp comment --content "Text" --on <recording_id> --in <project> --json` |
|
||||
| Post message | `basecamp message "Title" "Body" --in <project> --json` |
|
||||
| Post silently | `basecamp message "Title" "Body" --no-subscribe --in <project> --json` |
|
||||
| Post to campfire | `basecamp campfire post "Message" --in <project> --json` |
|
||||
| Add comment | `basecamp comment <recording_id> "Text" --in <project> --json` |
|
||||
| Search | `basecamp search "query" --json` |
|
||||
| Parse URL | `basecamp url parse "<url>" --json` |
|
||||
| Download file | `basecamp files download <id> --in <project>` |
|
||||
@@ -152,7 +176,7 @@ Returns: `account_id`, `project_id`, `type`, `recording_id`, `comment_id` (from
|
||||
# Comments are flat - reply to the parent recording_id, not the comment_id
|
||||
basecamp url parse "https://...messages/123#__recording_456" --json
|
||||
# Returns recording_id: 123 (parent), comment_id: 456 (fragment) - comment on 123, not 456
|
||||
basecamp comment --content "Reply" --on 123 --in <project>
|
||||
basecamp comment 123 "Reply" --in <project>
|
||||
```
|
||||
|
||||
## Decision Trees
|
||||
@@ -161,10 +185,14 @@ basecamp comment --content "Reply" --on 123 --in <project>
|
||||
|
||||
```
|
||||
Need to find something?
|
||||
├── Know the type + project? → basecamp <type> --in <project> --json
|
||||
├── Need cross-project data? → basecamp recordings <type> --json (ONLY cross-project option)
|
||||
├── Know the type + project? → basecamp <type> list --in <project> --json
|
||||
│ (some groups have default list behavior; use --agent --help if unsure)
|
||||
├── My assigned work? → basecamp reports assigned --json (defaults to "me")
|
||||
├── Overdue across projects? → basecamp reports overdue --json
|
||||
├── Browse by type cross-project? → basecamp recordings <type> --json
|
||||
│ (types: todos, messages, documents, comments, cards, uploads)
|
||||
│ Note: Defaults to active status; use --status archived for archived items
|
||||
│ ⚠ No assignee data — cannot filter by person; use reports assigned instead
|
||||
├── Full-text search? → basecamp search "query" --json
|
||||
└── Have a URL? → basecamp url parse "<url>" --json
|
||||
```
|
||||
@@ -187,7 +215,7 @@ Want to change something?
|
||||
# Get commit info and comment on todo (use printf %q for safe quoting)
|
||||
COMMIT=$(git rev-parse --short HEAD)
|
||||
MSG=$(git log -1 --format=%s)
|
||||
basecamp comment --content "Commit $COMMIT: $(printf '%s' "$MSG")" --on <todo_id> --in <project>
|
||||
basecamp comment <todo_id> "Commit $COMMIT: $(printf '%s' "$MSG")" --in <project>
|
||||
|
||||
# Complete when done
|
||||
basecamp done <todo_id>
|
||||
@@ -197,11 +225,11 @@ basecamp done <todo_id>
|
||||
|
||||
```bash
|
||||
# Create todo for PR work
|
||||
basecamp todo --content "Review PR #42" --in <project> --assignee me --due tomorrow
|
||||
basecamp todo "Review PR #42" --in <project> --assignee me --due tomorrow
|
||||
|
||||
# When merged
|
||||
basecamp done <todo_id>
|
||||
basecamp campfire post --content "Merged PR #42" --in <project>
|
||||
basecamp campfire post "Merged PR #42" --in <project>
|
||||
```
|
||||
|
||||
### Bulk Process Overdue Todos
|
||||
@@ -235,24 +263,26 @@ basecamp files download <upload_id> --in <project> --out ./downloads
|
||||
### Projects
|
||||
|
||||
```bash
|
||||
basecamp projects --json # List all
|
||||
basecamp projects show <id> --json # Show details
|
||||
basecamp projects create --name "Name" --json # Create
|
||||
basecamp projects update <id> --name "New" # Update
|
||||
basecamp projects list --json # List all
|
||||
basecamp projects show <id> --json # Show details
|
||||
basecamp projects create "Name" --json # Create
|
||||
basecamp projects update <id> --name "New" # Update
|
||||
```
|
||||
|
||||
### Todos
|
||||
|
||||
```bash
|
||||
basecamp todos --in <project> --json # List in project
|
||||
basecamp todos --assignee me --in <project> # My todos
|
||||
basecamp todos --overdue --in <project> # Overdue only
|
||||
basecamp todos --status completed --in <project> # Completed
|
||||
basecamp todos --list <todolist_id> --in <project> # In specific list
|
||||
basecamp todo --content "Task" --in <project> --list <list> --assignee me --due tomorrow
|
||||
basecamp done <id> [id...] # Complete (multiple OK)
|
||||
basecamp reopen <id> # Uncomplete
|
||||
basecamp todos position <id> --to 1 # Move to top
|
||||
basecamp todos list --in <project> --json # List in project
|
||||
basecamp todos list --assignee me --in <project> # My todos
|
||||
basecamp todos list --overdue --in <project> # Overdue only
|
||||
basecamp todos list --status completed --in <project> # Completed
|
||||
basecamp todos list --list <todolist_id> --in <project> # In specific list
|
||||
basecamp todo "Task" --in <project> --list <list> --assignee me --due tomorrow
|
||||
basecamp done <id> [id...] # Complete (multiple OK)
|
||||
basecamp reopen <id> # Uncomplete
|
||||
basecamp assign <id> --to <person> --in <project> # Assign (person: ID, email, or "me")
|
||||
basecamp unassign <id> --from <person> --in <project> # Remove assignee
|
||||
basecamp todos position <id> --to 1 # Move to top
|
||||
basecamp todos sweep --overdue --complete --comment "Done" --in <project>
|
||||
```
|
||||
|
||||
@@ -263,11 +293,11 @@ basecamp todos sweep --overdue --complete --comment "Done" --in <project>
|
||||
Todolists are containers for todos. Create a todolist before adding todos.
|
||||
|
||||
```bash
|
||||
basecamp todolists --in <project> --json # List todolists
|
||||
basecamp todolists show <id> --in <project> # Show details
|
||||
basecamp todolists create --name "Name" --in <project> --json # Create
|
||||
basecamp todolists create --name "Name" --description "Desc" --in <project>
|
||||
basecamp todolists update <id> --name "New" --in <project> # Update
|
||||
basecamp todolists list --in <project> --json # List todolists
|
||||
basecamp todolists show <id> --in <project> # Show details
|
||||
basecamp todolists create "Name" --in <project> --json # Create
|
||||
basecamp todolists create "Name" --description "Desc" --in <project>
|
||||
basecamp todolists update <id> --name "New" --in <project> # Update
|
||||
```
|
||||
|
||||
### Cards (Kanban)
|
||||
@@ -275,14 +305,14 @@ basecamp todolists update <id> --name "New" --in <project> # Update
|
||||
**Note:** Cards do NOT support `--assignee` filtering like todos. Fetch all cards and filter client-side if needed. If a project has multiple card tables, you must specify `--card-table <id>`. When you get an "Ambiguous card table" error, the hint shows available table IDs and names.
|
||||
|
||||
```bash
|
||||
basecamp cards --in <project> --json # All cards
|
||||
basecamp cards --card-table <id> --in <project> # Cards from specific table (required if multiple)
|
||||
basecamp cards --column <id> --in <project> # Cards in column
|
||||
basecamp cards columns --in <project> --json # List columns (needs --card-table if multiple)
|
||||
basecamp cards show <id> --in <project> # Card details
|
||||
basecamp card --title "Title" --content "<p>Body</p>" --in <project> --column <id>
|
||||
basecamp cards list --in <project> --json # All cards
|
||||
basecamp cards list --card-table <id> --in <project> # Specific table (required if multiple)
|
||||
basecamp cards list --column <id> --in <project> # Cards in column
|
||||
basecamp cards columns --in <project> --json # List columns (needs --card-table if multiple)
|
||||
basecamp cards show <id> --in <project> # Card details
|
||||
basecamp card "Title" "<p>Body</p>" --in <project> --column <id>
|
||||
basecamp cards update <id> --title "New" --due tomorrow --assignee me
|
||||
basecamp cards move <id> --to <column_id> # Move to column (numeric ID)
|
||||
basecamp cards move <id> --to <column_id> # Move to column (numeric ID)
|
||||
basecamp cards move <id> --to "Done" --card-table <table_id> # Move by name (needs table)
|
||||
```
|
||||
|
||||
@@ -293,7 +323,7 @@ basecamp cards move <id> --to "Done" --card-table <table_id> # Move by name (ne
|
||||
**Card Steps (checklists):**
|
||||
```bash
|
||||
basecamp cards steps <card_id> --in <project> # List steps
|
||||
basecamp cards step create --title "Step" --card <id> --in <project>
|
||||
basecamp cards step create "Step" --card <id> --in <project>
|
||||
basecamp cards step complete <step_id> --in <project>
|
||||
basecamp cards step uncomplete <step_id>
|
||||
```
|
||||
@@ -301,7 +331,7 @@ basecamp cards step uncomplete <step_id>
|
||||
**Column management:**
|
||||
```bash
|
||||
basecamp cards column show <id> --in <project>
|
||||
basecamp cards column create --title "Name" --in <project>
|
||||
basecamp cards column create "Name" --in <project>
|
||||
basecamp cards column update <id> --title "New"
|
||||
basecamp cards column move <id> --position 2
|
||||
basecamp cards column color <id> --color blue
|
||||
@@ -312,35 +342,41 @@ basecamp cards column watch <id> # Subscribe to column
|
||||
### Messages
|
||||
|
||||
```bash
|
||||
basecamp messages --in <project> --json # List messages
|
||||
basecamp messages show <id> --in <project> # Show message
|
||||
basecamp message --subject "Title" --content "Body" --in <project>
|
||||
basecamp messages update <id> --subject "New" --content "Updated"
|
||||
basecamp messages pin <id> --in <project> # Pin to top
|
||||
basecamp messages unpin <id> # Unpin
|
||||
basecamp messages list --in <project> --json # List messages
|
||||
basecamp messages show <id> --in <project> # Show message
|
||||
basecamp message "Title" "Body" --in <project>
|
||||
basecamp messages update <id> --title "New" --body "Updated"
|
||||
basecamp messages pin <id> --in <project> # Pin to top
|
||||
basecamp messages unpin <id> # Unpin
|
||||
```
|
||||
|
||||
**Flags:** `--draft` (create as draft), `--message-board <id>` (if multiple boards)
|
||||
**Flags:** `--draft` (create as draft), `--no-subscribe` (silent, no notifications), `--subscribe "people"` (comma-separated names, emails, IDs, or "me"; mutually exclusive with `--no-subscribe`), `--message-board <id>` (if multiple boards)
|
||||
|
||||
```bash
|
||||
basecamp message "Bot update" "Done" --no-subscribe --in <project>
|
||||
basecamp message "FYI" "Note" --subscribe "Alice,bob@x.com" --in <project>
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
```bash
|
||||
basecamp comments --on <recording_id> --in <project> --json
|
||||
basecamp comment --content "Text" --on <recording_id> --in <project>
|
||||
basecamp comments update <id> --content "Updated" --in <project>
|
||||
basecamp comments list <recording_id> --in <project> --json
|
||||
basecamp comment <recording_id> "Text" --in <project>
|
||||
basecamp comments update <id> "Updated" --in <project>
|
||||
```
|
||||
|
||||
### Files & Documents
|
||||
|
||||
```bash
|
||||
basecamp files --in <project> --json # List all (folders, files, docs)
|
||||
basecamp files --vault <folder_id> --in <project> # List folder contents
|
||||
basecamp files show <id> --in <project> # Show item (auto-detects type)
|
||||
basecamp files download <id> --in <project> # Download file
|
||||
basecamp files download <id> --out ./dir # Download to specific dir
|
||||
basecamp files folder create --name "Folder" --in <project>
|
||||
basecamp files doc create --title "Doc" --content "Body" --in <project>
|
||||
basecamp files doc create --title "Draft" --draft --in <project>
|
||||
basecamp files list --in <project> --json # List all (folders, files, docs)
|
||||
basecamp files list --vault <folder_id> --in <project> # List folder contents
|
||||
basecamp files show <id> --in <project> # Show item (auto-detects type)
|
||||
basecamp files download <id> --in <project> # Download file
|
||||
basecamp files download <id> --out ./dir # Download to specific dir
|
||||
basecamp files folder create "Folder" --in <project>
|
||||
basecamp files doc create "Doc" "Body" --in <project>
|
||||
basecamp files doc create "Draft" --draft --in <project>
|
||||
basecamp files doc create "Notes" "..." --no-subscribe --in <project>
|
||||
basecamp files update <id> --title "New" --content "Updated"
|
||||
```
|
||||
|
||||
@@ -355,11 +391,12 @@ basecamp schedule show <id> --in <project> # Entry details
|
||||
basecamp schedule show <id> --date 20240315 # Specific occurrence (recurring)
|
||||
basecamp schedule create "Event" --starts-at "2024-03-15T09:00:00Z" --ends-at "2024-03-15T10:00:00Z" --in <project>
|
||||
basecamp schedule create "Meeting" --all-day --notify --participants 1,2,3 --in <project>
|
||||
basecamp schedule create "Sync" --starts-at "..." --ends-at "..." --no-subscribe --in <project>
|
||||
basecamp schedule update <id> --summary "New title" --starts-at "..."
|
||||
basecamp schedule settings --include-due --in <project> # Include todos/cards due dates
|
||||
```
|
||||
|
||||
**Flags:** `--all-day`, `--notify`, `--participants <ids>`, `--status` (active/archived/trashed)
|
||||
**Flags:** `--all-day`, `--notify`, `--participants <ids>`, `--no-subscribe`, `--subscribe "people"` (mutually exclusive), `--status` (active/archived/trashed)
|
||||
|
||||
### Check-ins
|
||||
|
||||
@@ -369,10 +406,10 @@ basecamp checkins questions --in <project> # List questions
|
||||
basecamp checkins question <id> --in <project> # Question details
|
||||
basecamp checkins answers <question_id> --in <project> # List answers
|
||||
basecamp checkins answer <id> --in <project> # Answer details
|
||||
basecamp checkins question create --title "What did you work on?" --in <project>
|
||||
basecamp checkins question update <id> --title "New question" --frequency every_week
|
||||
basecamp checkins answer create --question <id> --content "My answer" --in <project>
|
||||
basecamp checkins answer update <id> --content "Updated" --in <project>
|
||||
basecamp checkins question create "What did you work on?" --in <project>
|
||||
basecamp checkins question update <id> "New question" --frequency every_week
|
||||
basecamp checkins answer create <question-id> "My answer" --in <project>
|
||||
basecamp checkins answer update <id> "Updated" --in <project>
|
||||
```
|
||||
|
||||
**Schedule options:** `--frequency` (every_day, every_week, every_other_week, every_month, on_certain_days), `--days 1,2,3,4,5` (0=Sun), `--time "5:00pm"`
|
||||
@@ -392,7 +429,7 @@ basecamp timeline --watch --interval 60 # Poll every 60 seconds
|
||||
|
||||
### Recordings (Cross-project)
|
||||
|
||||
Use `basecamp recordings <type>` for cross-project queries - this is the only way to query across all projects in one call.
|
||||
Use `basecamp recordings <type>` for cross-project type browsing. **For assigned todos, prefer `basecamp reports assigned`** — recordings do not include assignee data and cannot be filtered by person.
|
||||
|
||||
```bash
|
||||
basecamp recordings todos --json # All todos across projects
|
||||
@@ -433,12 +470,12 @@ basecamp templates construction <template_id> <construction_id> # Check status
|
||||
### Webhooks
|
||||
|
||||
```bash
|
||||
basecamp webhooks --in <project> --json # List webhooks
|
||||
basecamp webhooks show <id> --in <project> # Webhook details
|
||||
basecamp webhooks create --url "https://..." --in <project>
|
||||
basecamp webhooks create --url "https://..." --types "Todo,Comment" --in <project>
|
||||
basecamp webhooks list --in <project> --json # List webhooks
|
||||
basecamp webhooks show <id> --in <project> # Webhook details
|
||||
basecamp webhooks create "https://..." --in <project>
|
||||
basecamp webhooks create "https://..." --types "Todo,Comment" --in <project>
|
||||
basecamp webhooks update <id> --active --in <project>
|
||||
basecamp webhooks update <id> --inactive # Disable
|
||||
basecamp webhooks update <id> --inactive # Disable
|
||||
basecamp webhooks delete <id> --in <project>
|
||||
```
|
||||
|
||||
@@ -447,19 +484,19 @@ basecamp webhooks delete <id> --in <project>
|
||||
### Subscriptions
|
||||
|
||||
```bash
|
||||
basecamp subscriptions <recording_id> --in <project> # Who's subscribed
|
||||
basecamp subscriptions subscribe <id> --in <project> # Subscribe yourself
|
||||
basecamp subscriptions unsubscribe <id> # Unsubscribe
|
||||
basecamp subscriptions add <id> --people 1,2,3 # Add people
|
||||
basecamp subscriptions remove <id> --people 1,2,3 # Remove people
|
||||
basecamp subscriptions <recording_id> # Who's subscribed
|
||||
basecamp subscriptions subscribe <id> # Subscribe yourself
|
||||
basecamp subscriptions unsubscribe <id> # Unsubscribe
|
||||
basecamp subscriptions add <id> --people 1,2,3 # Add people
|
||||
basecamp subscriptions remove <id> --people 1,2,3 # Remove people
|
||||
```
|
||||
|
||||
### Lineup (Account-wide Markers)
|
||||
|
||||
```bash
|
||||
basecamp lineup create "Milestone" "2024-03-15" # Create marker
|
||||
basecamp lineup create --name "Launch" --date tomorrow
|
||||
basecamp lineup update <id> --name "New Name" --date "+7"
|
||||
basecamp lineup create "Launch" tomorrow # Natural date parsing
|
||||
basecamp lineup update <id> "New Name" "+7"
|
||||
basecamp lineup delete <id>
|
||||
```
|
||||
|
||||
@@ -470,7 +507,7 @@ basecamp lineup delete <id>
|
||||
```bash
|
||||
basecamp campfire --in <project> --json # List campfires
|
||||
basecamp campfire messages --in <project> --json # List messages
|
||||
basecamp campfire post --content "Hello!" --in <project>
|
||||
basecamp campfire post "Hello!" --in <project>
|
||||
basecamp campfire line <line_id> --in <project> # Show line
|
||||
basecamp campfire delete <line_id> --in <project> # Delete line
|
||||
```
|
||||
@@ -478,12 +515,12 @@ basecamp campfire delete <line_id> --in <project> # Delete line
|
||||
### People
|
||||
|
||||
```bash
|
||||
basecamp people --json # All people in account
|
||||
basecamp people --in <project> --json # People on project
|
||||
basecamp me --json # Current user
|
||||
basecamp people show <id> --json # Person details
|
||||
basecamp people add <id> --in <project> # Add to project
|
||||
basecamp people remove <id> --in <project> # Remove from project
|
||||
basecamp people list --json # All people in account
|
||||
basecamp people list --project <project> --json # People on project
|
||||
basecamp me --json # Current user
|
||||
basecamp people show <id> --json # Person details
|
||||
basecamp people add <id> --project <project> # Add to project
|
||||
basecamp people remove <id> --project <project> # Remove from project
|
||||
```
|
||||
|
||||
### Search
|
||||
@@ -534,6 +571,18 @@ basecamp config set project_id <id>
|
||||
basecamp config set todolist_id <id>
|
||||
```
|
||||
|
||||
**Config Trust:**
|
||||
|
||||
Authority keys (`base_url`, `default_profile`, `profiles`) in local/repo configs are blocked until explicitly trusted. This prevents a cloned repo's config from redirecting OAuth tokens.
|
||||
|
||||
```bash
|
||||
basecamp config trust # Trust nearest .basecamp/config.json
|
||||
basecamp config trust /path/to/.basecamp/config.json # Trust specific config file
|
||||
basecamp config trust --list # Show all trusted configs
|
||||
basecamp config untrust # Revoke trust for nearest config
|
||||
basecamp config untrust /path/to/.basecamp/config.json # Revoke trust for specific path
|
||||
```
|
||||
|
||||
**Check context:**
|
||||
```bash
|
||||
cat .basecamp/config.json 2>/dev/null || echo "No project configured"
|
||||
@@ -553,8 +602,8 @@ basecamp doctor --json # Check CLI health, auth, conn
|
||||
**Authentication errors:**
|
||||
```bash
|
||||
basecamp auth status # Check auth
|
||||
basecamp auth login # Re-authenticate (full access)
|
||||
basecamp auth login --scope read # Read-only access
|
||||
basecamp auth login # Re-authenticate
|
||||
basecamp auth login --scope full # Full access (BC3 OAuth only)
|
||||
```
|
||||
|
||||
**Network errors / localhost URLs:**
|
||||
@@ -571,12 +620,61 @@ basecamp auth status # Verify auth working
|
||||
cat ~/.config/basecamp/accounts.json # Check available accounts
|
||||
```
|
||||
|
||||
**Invalid flag errors:** All shortcut commands require explicit flags:
|
||||
- `basecamp todo --content "text"` (not `basecamp todo "text"`)
|
||||
- `basecamp card --title "title"` (not `basecamp card "title"`)
|
||||
**Required arguments are positional (not flags):**
|
||||
- `basecamp todo "Buy milk"` (not `--content`)
|
||||
- `basecamp card "New feature"` (not `--title`)
|
||||
- `basecamp message "Subject" "Body"` (not `--subject`)
|
||||
- `basecamp campfire post "Hello"` (not `--content`)
|
||||
- `basecamp comment <id> "Text"` (not a flag)
|
||||
- `basecamp webhooks create "https://..." --in <project>` (not `--url`)
|
||||
- `basecamp checkins answer create <question-id> "content"` (not `--question`)
|
||||
|
||||
**Missing argument errors (code: "usage"):**
|
||||
When a required positional argument is missing, the CLI returns a structured error naming
|
||||
the specific argument. Use this for elicitation:
|
||||
|
||||
```bash
|
||||
$ basecamp todo --json
|
||||
{"ok": false, "error": "<content> required", "code": "usage",
|
||||
"hint": "Usage: basecamp todo <content>"}
|
||||
|
||||
$ basecamp comments create 123 --json
|
||||
{"ok": false, "error": "<content> required", "code": "usage", ...}
|
||||
```
|
||||
|
||||
The `error` field names the missing `<arg>` — use it to prompt the user for the specific value.
|
||||
|
||||
**URL malformed (curl exit 3):** Special characters in content. Use plain text or properly escaped HTML.
|
||||
|
||||
## jq Patterns
|
||||
|
||||
Common data extraction patterns for the output envelope:
|
||||
|
||||
```bash
|
||||
# Extract fields from data array
|
||||
basecamp todos list --in <project> --json | jq '.data[] | select(.completed == false) | .title'
|
||||
basecamp todos list --in <project> --json | jq '.data | length'
|
||||
basecamp todos list --in <project> --json | jq '.data[] | {id, title, status}'
|
||||
|
||||
# Access envelope metadata
|
||||
basecamp todos list --in <project> --json | jq '.breadcrumbs[0].cmd'
|
||||
basecamp todos list --in <project> --json | jq '.meta.stats.requests'
|
||||
```
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Exit | Meaning | Fix |
|
||||
|------|---------|-----|
|
||||
| 0 | OK | — |
|
||||
| 1 | Usage error | Check `basecamp <cmd> --help` |
|
||||
| 2 | Not found | Verify ID/URL exists |
|
||||
| 3 | Auth error | `basecamp auth login` |
|
||||
| 4 | Forbidden | Check account/project permissions |
|
||||
| 5 | Rate limit | Wait and retry (resilience layer handles Retry-After automatically) |
|
||||
| 6 | Network error | Check connectivity, `basecamp doctor` |
|
||||
| 7 | API error | Retry; if persistent, check `basecamp doctor` |
|
||||
| 8 | Ambiguous | Be more specific (use ID instead of name) |
|
||||
|
||||
## Learn More
|
||||
|
||||
- API concepts: https://github.com/basecamp/bc3-api#key-concepts
|
||||
|
||||
Reference in New Issue
Block a user