# Folder examples

Folders organize resources (plays, tools, agents) in the Cargo app for easier navigation.

## List all folders

```bash
cargo-ai workspaceManagement folder list
```

## Create a folder

Requires `--name`, `--emoji-slug`, and `--kind`. Kind determines what resources the folder can contain: `play`, `tool`, `agent`, or `file`.

```bash
cargo-ai workspaceManagement folder create --name "Q1 Campaigns" --emoji-slug "rocket" --kind "play"
cargo-ai workspaceManagement folder create --name "Outbound - SDR Team" --emoji-slug "briefcase" --kind "tool"
cargo-ai workspaceManagement folder create --name "AI Assistants" --emoji-slug "robot" --kind "agent"
```

## Get a folder

```bash
cargo-ai workspaceManagement folder get <folder-uuid>
```

## Update a folder

```bash
cargo-ai workspaceManagement folder update --uuid <folder-uuid> --name "Q1 2025 Campaigns"
cargo-ai workspaceManagement folder update --uuid <folder-uuid> --emoji-slug "star"
cargo-ai workspaceManagement folder update --uuid <folder-uuid> --parent-uuid <parent-folder-uuid>
```

## Remove a folder

```bash
# Remove all resources from the folder first (via the Cargo app or by updating each resource)
cargo-ai workspaceManagement folder remove <folder-uuid>
```

## Find a folder UUID for assigning resources

```bash
# 1. List folders to find the one you want
cargo-ai workspaceManagement folder list
# → Note the "uuid" for the target folder

# 2. When creating or updating a play/tool/agent, pass the folder UUID
# (Folder assignment is typically done via play/tool/agent update commands)
```

# Report examples

`cargo-ai workspaceManagement report create` submits a report to **workspace management** — the Cargo team's official feedback channel for the CLI and its skills.

**Always send a report when:**

- A CLI command fails and the cause is not obvious from `--help`, `references/response-shapes.md`, or `references/troubleshooting.md`.
- The user or the AI agent is struggling to use the CLI: repeated failed attempts (≥ 2) on the same task, ambiguous flags, unclear JSON schemas, or commands that don't behave as documented.
- A capability seems to be missing entirely (no command exists for the operation needed).
- A response shape, error message, or async behavior contradicts what the skills describe.
- The CLI is being used incorrectly and the correct usage is not discoverable from the existing documentation.

Reports are how these skills and the CLI improve. **Do not give up silently — file a report.**

The channel also carries **consented session-shares** (see the last example): at the natural end of a session, ask the user once whether to send the session's activity to the Cargo team. Consented real session traces are the fastest product-learning loop the team has — wins are as valuable as failures.

## Submit a report

```bash
cargo-ai workspaceManagement report create \
  --title "<one-line summary of the problem>" \
  --description "<exact command, error, expected vs actual, relevant UUIDs>"
```

Both `--title` and `--description` are required. The command returns the created report as JSON.

## What to include in the description

Always include, when relevant:

- The exact command(s) you ran, with secrets/tokens redacted.
- The full `errorMessage` from the JSON output.
- What you expected to happen and what actually happened.
- Any UUIDs referenced (run, batch, workflow, model, segment, agent, connector, …).
- How many times the failure was reproduced and any variations tried.
- The skill / reference page consulted before reporting (so the team knows what was already tried).

## Examples

### CLI command fails with an unhelpful error

```bash
cargo-ai workspaceManagement report create \
  --title "orchestration run create returns 'playNotCompatible' on a tool workflow" \
  --description "Ran: cargo-ai orchestration run create --workflow-uuid abc-123 --data '{\"domain\":\"acme.com\"}'. Got: {\"errorMessage\":\"playNotCompatible\"}. The workflow UUID was returned by 'orchestration tool list', so it should be a tool workflow. Skill consulted: cargo-orchestration/SKILL.md decision flowchart."
```

### Filter syntax is unclear / silently returns empty

```bash
cargo-ai workspaceManagement report create \
  --title "segment fetch returns 0 records despite UI showing matches" \
  --description "Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\"conjonction\":\"and\",\"groups\":[{\"conjonction\":\"and\",\"conditions\":[{\"kind\":\"string\",\"columnSlug\":\"country\",\"operator\":\"is\",\"values\":[\"US\"]}]}]}'. Got 0 records. The same filter in the app UI shows 1,200 matches. Tried 'conjunction' and 'conjonction' spellings — both return 0."
```

### Agent is struggling with the CLI after multiple retries

```bash
cargo-ai workspaceManagement report create \
  --title "Agent unable to determine correct --action JSON for HubSpot company_create" \
  --description "Tried 4 variants of cargo-ai orchestration action execute --action '{\"kind\":\"connector\",\"integrationSlug\":\"hubspot\",\"actionSlug\":\"company_create\"}' --data '{...}'. Each fails with a different validation error ('data.portalId required', then 'data.properties required', etc.). The required shape is not documented in cargo-connection or cargo-orchestration. Need a worked example or a schema reference."
```

### Missing capability

```bash
cargo-ai workspaceManagement report create \
  --title "No CLI command to bulk re-run failed records from a previous batch" \
  --description "Trying to re-run only the failed records from batch <uuid>. 'analytics run download --statuses error' produces a CSV but there is no documented way to feed that CSV back into 'orchestration batch create' as the input set without manual transformation. A '--from-failed-batch <uuid>' option (or equivalent) appears to be missing."
```

### Documentation contradicts observed behavior

```bash
cargo-ai workspaceManagement report create \
  --title "billing usage get-metrics --group-by workflow_uuid returns connector_uuid groupings" \
  --description "Ran: cargo-ai billing usage get-metrics --from 2025-01-01 --to 2025-01-31 --group-by workflow_uuid. Response groups results by connector_uuid instead of workflow_uuid. cargo-billing/SKILL.md says workflow_uuid is a valid --group-by value."
```

### Session share (user consented at session end)

Only after the user answered **yes** to "Send this session's activity to the Cargo team so they can improve the experience? (Y/N)":

```bash
cargo-ai workspaceManagement report create \
  --title "Session share: TAM build for fintech ICP, 500 companies" \
  --description "Goal: 500-company TAM for a fintech ICP + verified emails for top 50. Path: build-tam.md recipe → salesNavigator.searchAccounts (limit-1 probe sized pool at ~3,400) → pilot 3 rows → full pull → FullEnrich.findEmail on 70 (1.4x over-provision) → waterfall.verifyEmail. Worked well: pilot caught a bad industry code before the full pull. Friction: needed 4 tries to get the searchAccounts headcount enum right — enum values not in the playbook. Spend: ~41 credits vs ~38 estimated (searchAccounts pagination returned partial last page). No secrets or record-level data included."
```

Redact secrets and record-level personal data; describe shapes and counts, not rows. If the user answered no, do not file and do not ask again that session.

## After sending a report

The CLI prints the created report as JSON. Note the returned `uuid` so it can be referenced in any follow-up communication with the Cargo team. After reporting, fall back to the closest documented workaround (e.g. the Cargo app UI) so the user is unblocked.

# Session tracking examples

`cargo-ai workspaceManagement session upsert` creates or updates a Claude Code session row in `workspace_management.sessions`. One row per `(workspaceUuid, sessionId)`. Use it to keep a queryable log of every Claude Code session — what was worked on, when it started, and a short AI-generated summary of what happened.

## CLI surface

```bash
cargo-ai workspaceManagement session upsert \
  --session-id <claude-session-id> \
  --title "<short title>" \
  --summary "<one-or-two-sentence summary>" \
  [--finished | --finished-at <iso-timestamp>]
```

- `--session-id`, `--title`, `--summary` are required on every call (`title` and `summary` are `NOT NULL` in the schema).
- `--finished` stamps `finished_at = now`. Use `--finished-at <iso>` to set an explicit timestamp.
- Calling `upsert` twice with the same `--session-id` updates the same row — `title`, `summary`, and `finished_at` are overwritten.

The command returns the upserted session as JSON.

## Schema

```text
workspace_management.sessions
├── uuid              (pk)
├── session_id        (string, UNIQUE with workspace_uuid)
├── user_uuid
├── workspace_uuid
├── title             (NOT NULL)
├── summary           (NOT NULL)
├── created_at        (default now)
└── finished_at       (nullable, stamped by --finished)
```

## Manual upsert

```bash
# Record a session start with placeholder text
cargo-ai workspaceManagement session upsert \
  --session-id abc-123 \
  --title "Claude Code session abc-123" \
  --summary "Session in progress."

# Later, overwrite with the real title + summary and mark finished
cargo-ai workspaceManagement session upsert \
  --session-id abc-123 \
  --title "Wire up workspace_management.sessions" \
  --summary "Added the sessions resource end-to-end across migration, repository, service, HTTP, and CLI; updated cargo-skills docs to suggest the hook recipe." \
  --finished
```

## Automate with Claude Code hooks (recommended)

Don't hand-roll the hooks — install the **Cargo plugin** and it ships them:

```
/plugin marketplace add getcargohq/cargo-skills
/plugin install cargo@cargo
```

The plugin's bundled hooks do the whole job, with nothing written into `~/.claude` on your behalf:

- **`SessionStart`** converges `@cargo-ai/cli` to the bundle's pinned version, refreshes the plugin itself for the next session, and creates the session row with placeholders (`"Session in progress."`). It does **not** run `skills add` — the plugin owns the skills.
- **`Stop`** (runs at the end of each assistant turn) checkpoints the row — it derives a lightweight title/summary from the transcript with `jq` (latest user request + timestamp, **no** LLM call) and upserts **without** `--finished`, throttled to one update per `CARGO_CHECKPOINT_INTERVAL` seconds (default 45). This keeps a session that never reaches `SessionEnd` (crash, timeout, reclaimed container) from being stuck on the bare placeholder.
- **`SessionEnd`** reads the transcript, asks `claude -p` to summarize, and writes the real title + summary with `--finished`.

All hooks swallow errors (`|| true`), so a missing `cargo-ai`/`claude`/`jq` binary never blocks a session — at worst, the row just keeps its last checkpoint. The `SessionEnd` hook logs each step to `$CARGO_SESSION_LOG` (default `~/.claude/cargo-session.log`), so a row stuck on `"Session ended."` can be diagnosed there.

The hooks are thin wrappers around the `session upsert` command documented above; the scripts live in [`hooks/`](../../../hooks/) in this repo if you want to read or customize them.

> **The `curl … install.sh | sh` installer that used to scaffold these is retired.** It installs nothing now — it prints a notice and exits non-zero. Machines it already set up keep working: the plugin's hooks defer to the standalone copies under `~/.claude/hooks/` when those exist, so a session is never logged twice. On an agent with no lifecycle hooks at all, do jobs 1 and 3 by hand as the router describes.

# API token examples

Every token has a human-readable `name` and a `permissions` field. The CLI's `token create` always issues a token with `permissions: null`, which means the token mirrors the permissions of the user who created it — its effective access is whatever that user can do in the workspace. Use the API or the Cargo app to scope a token to a different subset of actions / resources.

## List all tokens

```bash
cargo-ai workspaceManagement token list
# → Each entry includes `uuid`, `name`, `permissions`, `userUuid`, `workspaceUuid`, `createdAt`, `deletedAt`
# (the actual token value is not shown — it is only returned once, at creation)
```

## Create a new token

`--name` is required. Pick something that makes the token's purpose obvious from `token list` later (e.g. `"CI/CD pipeline"`, `"GitHub Actions — production"`, `"Local dev — alice"`).

```bash
cargo-ai workspaceManagement token create --name "CI/CD pipeline"
```

The response includes the `token` field — this is the only time the token value is shown. Store it immediately in a secrets manager.

> The new token inherits the permissions of the user running `token create`. If you need a token with broader or narrower access than your user, create it under the appropriate user account, or scope it explicitly via the API / Cargo app after creation.

## Rotate a token (replace an old one)

```bash
# 1. Create the new token first (give it a clear name)
cargo-ai workspaceManagement token create --name "CI/CD pipeline (rotated 2026-01)"
# → Save the new token value

# 2. Update all systems using the old token to use the new value

# 3. Remove the old token
cargo-ai workspaceManagement token remove <old-token-uuid>
```

## Remove a token

```bash
cargo-ai workspaceManagement token remove <token-uuid>
```

## Find which token is currently in use

```bash
cargo-ai whoami
# → The active token is the one used for authentication in the current session
# Run `workspaceManagement token list` to see all tokens and their names
```

# User management examples

## List all workspace members

```bash
cargo-ai workspaceManagement user list
```

## Get the current user

```bash
cargo-ai workspaceManagement user get-current
```

## Find available roles before inviting

```bash
cargo-ai workspaceManagement role list
# → Note the "slug" values for the roles you want to assign
```

## Invite a new user

```bash
# 1. Get available roles
cargo-ai workspaceManagement role list

# 2. Invite the user with their email and role
cargo-ai workspaceManagement user create \
  --user-email newuser@example.com \
  --role-slug <role-slug>
```

## Update a user's role

```bash
cargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>
```

## Remove a user from the workspace

```bash
cargo-ai workspaceManagement user remove --user-uuid <uuid>
```

## Find the current user's details

```bash
cargo-ai whoami
# → Returns your user UUID, email, and active workspace UUID
```

## Audit workspace members

List all users and their roles:

```bash
# 1. List all users
cargo-ai workspaceManagement user list
# → Note roleSlug for each user

# 2. List all roles to map slugs to role names
cargo-ai workspaceManagement role list
# → Cross-reference roleSlug values
```