feat: expand CLI to full API parity (agent-first)

Draft
SI
4mo ago
+3983-205

Goal

Make the CLI able to do everything the API can do (and better), designed agent-first following the cli-for-agents skill.

Both the API (~130 routes) and the existing CLI (10 thin command groups) were deeply mapped; the CLI now covers the full agent-facing API surface.

Agent-first design

  • Non-interactive: every input is a flag; no prompts ever.
  • stdin / pipelines: freeform text and JSON flags accept piped stdin (valueOrStdin), so commands compose — e.g. echo "..." | recoup generate.
  • Layered --help: each group ships copy-pasteable Examples:; agents discover incrementally (recoup → recoup research --help).
  • Fail fast: required combinations validated up front; errors include a corrected example invocation and exit non-zero.
  • Structured success: plain mode prints IDs/URLs; --json returns the raw API response on every command.
  • Predictable structure: consistent recoup <resource> <verb>.

What's new

Client — added patch / put / del verbs and robust response parsing (handles empty / non-JSON bodies).

Shared helpers — runAction (uniform error handling) and stdin (valueOrStdin, parseJsonFlag).

New command groups: accounts, catalogs, connectors, generate (non-streaming agent loop), models, pulses, research (28 endpoints incl. profile/audience/metrics/similar/tracks/web/deep/enrich/extract/snapshots), sessions, spotify, templates, workspaces.

Expanded groups:

  • artists — create / update / delete / fans / posts / socials / scrape
  • chats — update / delete / messages / artist / compact
  • content — caption / image / video / analyze / transcribe / upscale / edit / template
  • orgs — create / add-artist
  • sandboxes — file / upload / setup
  • songs — list
  • tasks — list / create / update / delete / runs

Tests

  • 156 tests passing (was 78), pnpm build green.
  • New tests for the client verbs, helpers, and every new/expanded command group, mocking client.js (and stdin.js where relevant).

Notes

  • pnpm lint currently errors repo-wide because no eslint.config.js exists (pre-existing ESLint v9 migration gap, unrelated to this change).
  • keys management is intentionally omitted: those endpoints require a Privy Authorization: Bearer token, while the CLI authenticates via x-api-key.
  • Version bumped 0.1.13 → 0.2.0.

🤖 Generated with Claude Code

Generated by Claude Code

Summary by cubic

Brings @recoupable/cli to full parity with the REST API using an agent-first, non-interactive design. Adds a no-network E2E smoke harness for the built binary and switches the default API base URL to production.

  • New Features

    • Agent-first UX: flags-only, stdin pipelines, layered --help with examples, fail-fast errors, and recoup <resource> <verb> structure.
    • HTTP client: adds patch, put, del and tolerant parsing for empty/non-JSON bodies.
    • Shared helpers: runAction (uniform errors) and stdin utils (valueOrStdin, parseJsonFlag).
    • New groups: accounts, catalogs, connectors, generate, models, pulses, research (28 endpoints), sessions, spotify, templates, workspaces.
    • Expanded groups: artists, chats, content (caption/image/video/analyze/transcribe/upscale/edit/template), orgs, sandboxes, songs, tasks.

  • Refactors

    • Centralized output via emit to standardize plain vs --json.
    • Tests: 156 unit tests plus a no-network E2E harness (pnpm e2e) that drives dist/bin.cjs with a fetch stub; 22 groups covered, 82/82 cases pass.
    • Default API base URL now https://api.recoupable.com (override with RECOUP_API_URL).
    • Version bump: 0.1.13 → 0.2.0.