junghoonghae/capacities-cli

capacities-cli — Unofficial CLI for Capacities.io

capacities-cli is a Rust CLI (command: capx) for managing your Capacities.io knowledge base from the terminal. It wraps the Capacities Portal API and supports full CRUD on objects, tasks, daily notes, weblinks, and more.

Disclaimer: This project is not affiliated with or endorsed by Capacities. "Capacities" is a trademark of Capacities GmbH.

Setup

Installation

cargo install capacities-cli

Or clone and build locally:

git clone https://github.com/JungHoonGhae/capacities-cli && cd capacities-cli && cargo build --release

Authentication

capx reads the auth token automatically from the Capacities desktop app's cookie database. Just make sure the Capacities app is installed and you're logged in.

Alternatively, set the CAP_TOKEN environment variable:

export CAP_TOKEN="your-auth-token"

Space Selection

The CLI auto-selects your first space. Override with:

export CAP_SPACE_ID="your-space-uuid"
# or per-command:
capx spaces  # find your space ID
capx search "query" --space-id <uuid>

Command Reference

Discovery

| Command | Usage | Purpose | |---------|-------|---------| | spaces | capx spaces | List all workspaces | | whoami | capx whoami | Check auth status | | search | capx search "query" --limit 20 | Full-text search | | types | capx types | List object types and their properties | | ls | capx ls or capx ls -t Page -t Person | List objects, optionally filtered by type | | get | capx get <id> [<id2>...] | View formatted objects | | get --raw | capx get <id> --raw | Raw API response (useful for inspecting property values) |

CRUD

| Command | Usage | |---------|-------| | create | capx create <Type> "Title" -d "desc" -b "body" -p key=value --context "term" | | update | capx update <id> -t "title" -d "desc" -b "body" -p key=value | | rm | capx rm <id> --yes | | undo | capx undo <id> | | dup | capx dup <id> | | trash | capx trash |

Specialized

| Command | Usage | |---------|-------| | task | capx task "Title" -b "body" -p status=next-up -p priority=high -c "context" | | daily | capx daily "markdown text" or capx daily "text" --no-timestamp | | daily get | capx daily get — Read today's daily note | | daily delete | capx daily delete --last 1 --yes — Delete last block | | daily delete | capx daily delete --marker "text" --yes — Delete blocks containing text | | daily set | capx daily set -b "# New content" --yes — Replace entire daily note | | link | capx link "https://..." -t "Title" -d "desc" | | context | capx context <object-id> "search term" [<uuid>...] |

Export & Edit

| Command | Usage | |---------|-------| | export | capx export — Export all objects as markdown to stdout | | export | capx export -t Page --format json — Export Pages as JSON | | export | capx export -o ./backup — Export to directory | | edit | capx edit <id> — Edit object in $EDITOR |

Diagnostics

| Command | Usage | |---------|-------| | auth | capx auth — Check authentication status | | doctor | capx doctor — Check API connection, auth, and config | | completions | capx completions bash — Generate shell completions (bash/zsh/fish) |

Global Flags

• --json — JSON output for scripting
• --space-id <UUID> — Override auto-detected space
• --appversion <VER> — Override Portal API app version (or set CAP_APPVERSION)
• --portal-url <URL> — Override Portal API base URL (or set CAP_PORTAL_URL)

Object Types

Run capx types to see the user's actual schema. Capacities ships with built-in types, and users can create custom ones. Common built-in types:

• Organization — Relation (label), Category (label), CEO (entity→Person), Employee (entity→Person), Contact Information (blocks), Website (entity→WebResource)
• Project — Status (label: Planned/In Progress/Completed/On Hold), Client Company (entity→Organization), Time frame (datetime)
• Person — Can be linked to Organization as CEO/Employee
• Task (RootTask) — status, priority, date, notes
• Page, Idea, Atomic note, Meeting, Place

Always run capx types first to discover the user's actual types and property names — custom types vary by user.

Property Types

The -p key=value flag auto-normalizes values based on the property's data type:

| Type | Example | Behavior | |------|---------|----------| | label | -p status=done | Case-insensitive match against defined options | | entity | -p CEO=<uuid> | Links to another entity by UUID | | blocks | -p "Notes=## Heading\n- item" | Markdown → Capacities block format | | datetime | -p date=2026-03-15 | Parses to ISO datetime | | string | -p title="New Title" | Plain text |

Context Linking

--context (on create, task) and the context command accept UUIDs or search terms. Search terms auto-resolve to the best match:

# Search term — auto-resolves
capx task "Review contract" --context "Acme Corp"

# UUID
capx context <object-id> 7ccca7ef-5c1f-4bf6-a098-4d50de921b20

# Multiple
capx create Project "Website Redesign" --context "Acme Corp" --context "Design Team"

Workflow Patterns

Registering information from screenshots or messages

When the user shares a screenshot (Slack, KakaoTalk, Teams, email, etc.) and wants to log it:

1. Extract key information from the image: who said what, dates, action items, project names
2. Search for existing entities: capx search "company or project name"
3. Create missing entities in dependency order:
   • Organization (if new): capx create Organization "Name" -p Relation=Client -p Category=Company
   • Person: capx create Person "Name" -d "Role at Company" --context "Company Name"
   • Project: capx create Project "Name" -p Status="In Progress" --context "Company Name"
4. Create task(s) with structured body and context links:

   capx task "[Project] Task description" \
     -b "$(cat <<'EOF'
   ## Source
   - Key point from message
   - Action item with deadline
   - People involved
   EOF
   )" \
     -p status=next-up -p priority=high \
     --context "Project Name"
   

5. Enrich entities — search the web for company details, then fill in properties:

   capx update <org-id> -d "Brief description" -b "## Details..."
   capx update <org-id> -p CEO=<person-uuid> -p Website=<weblink-uuid>
   

The dependency order matters because --context resolves search terms at creation time — the target entity must already exist.

Archiving completed tasks

1. Search: capx search "project name" to find related tasks
2. Inspect: capx get <id1> <id2> ... --raw to check current status values
3. Identify: look for "status": {"val": ["done"]} in the raw output
4. Archive: capx update <id> -p status=archived for each completed task
5. Run updates in parallel when archiving multiple tasks

Building a complete company profile

1. capx create Organization "Acme Corp" -p Relation=Client -p Category=Company
2. Search the web for company info (CEO name, address, phone, website URL)
3. capx create Person "Jane Doe" -d "CEO of Acme Corp"
4. capx link "https://acme.com" -t "Acme Corp Website"
5. Wire everything together:

   capx update <org-id> \
     -d "Short company description" \
     -b "$(cat <<'EOF'
   ## Company Info
   - **Founded**: 2015
   - **Employees**: 50
   - **Address**: 123 Main St
   
   ## Contact
   - **Phone**: 555-0100
   - **Email**: [email protected]
   EOF
   )" \
     -p CEO=<person-uuid> \
     -p Employee=<person-uuid> \
     -p Website=<weblink-uuid> \
     -p "Contact Information=**Phone**: 555-0100\n**Email**: [email protected]"
   

Enriching organization notes from external data

When syncing information from emails, CRM, or other sources into an Organization's notes:

1. Gather data from external source (emails, project files, etc.)
2. Update notes with structured markdown — contacts, activity timeline, pending items:

   capx update <org-id> -b "$(cat <<'EOF'
   ## Contacts
   | Name | Role | Email |
   |------|------|-------|
   | Jane Doe | CEO | [email protected] |
   | John Smith | CTO | [email protected] |
   
   ## Recent Activity
   - **2026-03**: SSL certificate renewed
   - **2026-02**: API credentials migrated
   
   ## Pending Items
   - Contract renewal due Q2
   EOF
   )"
   

Note: -b replaces the entire notes body. To preserve existing notes, read first with capx get <id> and merge content.

Bulk updating tasks

When updating multiple tasks (e.g., reconciling statuses from email evidence), run updates in parallel for efficiency:

# Update statuses in parallel
capx update <id1> -p status=done &
capx update <id2> -p status=done &
capx update <id3> -p status=in-progress &
wait

Or from a script, loop through IDs:

for id in <id1> <id2> <id3>; do
  capx update "$id" -p status=done
done

Important: Only pass the properties you intend to change. Extra -p flags overwrite existing values — omitting a property leaves it unchanged.

Daily notes

# Timestamped entry (default)
capx daily "Had sync with design team. Agreed on new dashboard layout."

# Multi-line, no timestamp
capx daily "$(cat <<'EOF'
## Sprint Review
- Completed auth module
- Started API integration
- Blocked on database migration
EOF
)" --no-timestamp

Task Properties

| Property | Values | |----------|--------| | status | not-started, next-up, in-progress, done, archived | | priority | low, medium, high | | date | ISO date (e.g., 2026-03-15) |

Tips

• Create entities in dependency order: Organization → Person → Project → Task (so context links resolve)
• Use --raw with get to see actual property structures when debugging
• --context accepts plain search terms — no need to look up UUIDs first
• Body (-b) supports markdown: headings, bold, italic, code blocks, links, tables
• Use heredoc $(cat <<'EOF' ... EOF) for multi-line body content
• Batch operations: pass multiple IDs to get for efficient retrieval
• All commands support --json for scripting and piping

Gotchas

• get with multiple task IDs may fail: capx get <id1> <id2> can return "No objects found" for RootTask entities. Workaround: get tasks individually with capx get <id> --raw.
• Empty status arrays: Some tasks have "status": {"val": []} (no status set) in raw output. Handle this in scripts with fallback defaults.
• -p date= sets date resolution to day: When setting task dates, use ISO format (2026-03-15). Omitting -p date= on update leaves the existing date unchanged.
• -b replaces entire notes: The body flag overwrites all existing notes/blocks content. There is no append mode — read existing content first if you need to merge.