@cmgfi/xdpict-cli

Command-line client for XDpict — task management + AI-context generation + wiki access from the terminal.

npm install -g @cmgfi/xdpict-cli
xdpict auth login           # paste a token from /settings/integrations
xdpict tasks list --mine

Requirements

• Node.js 18 or newer
• An XDpict account on the CMG workspace
• A personal API access token — generate one at Settings → Integrations in the web UI

Auth

xdpict auth login [<token>]    # paste a token; prompts interactively if omitted
xdpict auth status              # show signed-in user + token fingerprint
xdpict auth logout              # delete the local token

Tokens are stored at:

| Platform | Path | |---|---| | macOS / Linux | ~/.config/xdpict/auth.json (or $XDG_CONFIG_HOME/xdpict/auth.json) | | Windows | %APPDATA%\xdpict\auth.json |

File permissions are set to 0600 on Unix (silently ignored on Windows since %APPDATA% is already user-scoped).

Tasks

List tasks

xdpict tasks list                            # all tasks in your workspace
xdpict tasks list --mine                     # only tasks assigned to you
xdpict tasks list --project "Design Queue"   # filter by project (case-insensitive substring)
xdpict tasks list --format=table             # bordered grid
xdpict tasks list --json                     # raw JSON for piping

Default output is compact (one line per task) with TTY-detected color:

ab12cd34  in_progress  GHE Design Queue      Wire up the foo button       2026-06-15
ef56gh78  on_hold      Internal Tools        Migrate billing dashboard    -

--json also returns platform for each task, which makes it filterable and groupable without a second call.

Show a task

xdpict tasks show <uuid>
xdpict tasks show <uuid> --json

Full detail: title, status, priority, due date, projects + sections, assignees, tags, and the 5 most recent comments.

--json additionally returns five structured fields:

| Field | Type | Notes | |---|---|---| | platform | string \| null | The Platform/Project value as a bare name — Clear, not Platform: Clear. Maps directly onto a design system. | | aiContext | string \| null | The generated AI briefing, as stored. Not generated on demand by this call. | | xdContext | string \| null | The designer-authored context note. | | successCriteria | string \| null | Acceptance criteria, extracted from the source issue or AI-synthesised. | | attachments | { name, url, type }[] | Empty array when the task has none. |

Null and empty semantics matter if you are consuming this programmatically. These keys are always present. An unset value is null (or [] for attachments) — the key is never omitted — so you can read data.platform directly without an existence check, and data.attachments.length is always safe.

# platform comes back bare, ready to map onto a design system
xdpict tasks show ab12cd34 --json | jq -r '.platform'      # → Clear

# group a list by platform without a second call
xdpict tasks list --json | jq -r '.tasks[] | "\(.platform // "untagged")\t\(.title)"'

Every subcommand also documents its own flags:

xdpict tasks list --help
xdpict tasks show --help     # -h works too

Create a task

xdpict tasks create --project "Design Queue" --title "Triage incoming requests"
xdpict tasks create --project "Design Queue" --title "Fix nav bug" \
  --description "Sidebar collapses unexpectedly on mobile" \
  --priority high --due 2026-06-15

# Pipe a description from another command
git log -1 --format=%B | xdpict tasks create \
  --project "Design Queue" --title "Today's commit" --description-stdin

Project resolution is case-insensitive substring match; an exact-name match wins when multiple projects partially match.

Search

xdpict search "design system"
xdpict search "auth flow" --scope tasks         # only tasks
xdpict search "onboarding" --scope hub          # only wiki pages
xdpict search "feedback" --json

Output groups task hits and wiki hits, each with a [task] / [wiki] pill:

[task] ab12cd34   in_progress   GHE Design Queue   Reduce design feedback loop
[wiki] xy12ab34   Design feedback principles
        How we structure and timebox design reviews — a 5-step…

Workspace-scoped + uses the same pg_trgm relevance scoring as the web UI's Cmd+K search.

AI context

xdpict ai-context <task-uuid>                    # markdown to stdout, usage to stderr
xdpict ai-context <task-uuid> --json             # full envelope incl. token + cost
xdpict ai-context <task-uuid> > context.md       # capture to file

Wraps XDpict's "Generate AI context" feature — the same block the dashboard's button produces. Requires the designer or admin role on your account. Calls an LLM under the hood; expect 30–60 seconds per invocation. Token + cost telemetry print to stderr so the markdown body stays pipe-clean.

Wiki

xdpict hub design-system-principles              # render as Markdown
xdpict hub design-system-principles --raw        # original Tiptap HTML
xdpict hub design-system-principles --json       # full envelope

Looks up a page by slug within your workspace. The internal htmlToMarkdown pass handles common Tiptap output (headings, lists, links, inline emphasis); fall back to --raw if you need the source HTML.

Global flags

| Flag | What it does | |---|---| | --help, -h | Show top-level help, or command-specific help when after a subcommand | | --version, -v | Print CLI version | | --json | Emit raw JSON instead of formatted output | | --format=table | Render lists as a bordered table (where supported) |

Environment variables

| Variable | Effect | |---|---| | NO_COLOR | Disable ANSI color in output | | FORCE_COLOR | Force-enable ANSI color even when piped | | XDG_CONFIG_HOME | Override the config directory root (Linux/macOS) |

The CLI does not read API URLs from the environment in v1 — base URL is per-config and set during auth login.

Update check

Each invocation may print a one-line nudge to stderr if a newer version is published on npm. The check is daily (cached in state.json next to your token), non-blocking, and silent on network failure. To opt out: never sign in (the check runs only after the first command that needs a token), or pin the version in your install.

Troubleshooting

| Symptom | Likely cause | |---|---| | Unauthorized — token may be revoked. Run xdpict auth login. | Token was revoked from /settings/integrations or expired | | Task not found on tasks show | Full UUID required (v1) — short-prefix resolution is a follow-up | | AI context requires the designer role. | Your account is member; ask your workspace admin to flip the designer flag | | Rate limited. Wait a bit and try again. | AI-context rate limits per user — see XDpict's AI cost-cap policy | | EACCES writing to config dir on Linux | Check $XDG_CONFIG_HOME (if set) or ~/.config/xdpict/ ownership |

Internals

• Zero runtime dependencies. Built from TypeScript with tsc; ships transpiled JS in dist/.
• Hits /api/cli/* endpoints on the deployed xdpict app (Easy Auth–exempt namespace; Bearer-validated against the mcp_tokens table).
• Source lives in the xdpict monorepo at cli/.

License

UNLICENSED — internal to CMG.