Scripting Your Crates with the CLI

JSON-first, by design

The CLI is built for pipes, not just for people. It is JSON-first:

• stdout carries the result as JSON — ready to pipe into jq or any tool that reads JSON.
• stderr carries errors as a structured JSON error envelope, not a wall of prose. Failures are as parseable as successes.
• exit codes are stable, so scripts can branch reliably: - 1 — an API error, - 2 — a usage error, - 4 — a timeout.

Point it wherever your catalog lives with --base-url. By default it talks to your local catalog API; in cloud or crew setups you aim it at the host you want:

deadca7 --base-url https://catalog.example.com collections list

The CLI is generated from the API’s OpenAPI spec, so the commands and the REST endpoints stay in lockstep. Anything below has a matching route under /api.

The shape of a command

Commands read as subject then action. Start an import and watch it:

deadca7 imports create https://archive.org/details/<some-netlabel-collection>
deadca7 imports get <id>

imports create kicks off the same background, crash-safe, resumable workflow the command palette uses and returns an import id. imports get polls progress — state, albums done and total, track counts, and the collection id it’s building into. A simple wait loop is just the CLI plus jq:

id=$(deadca7 imports create "$URL" | jq -r '.id')
while [ "$(deadca7 imports get "$id" | jq -r '.state')" != "done" ]; do
  sleep 5
done

Browse and search from the terminal

Collections, playlists, contents, and artists all expose the familiar set of actions. Collections and playlists support list|create|get|update|delete; contents support list|create|get|delete, and its list takes a search term:

deadca7 collections list
deadca7 contents list "amen break"
deadca7 artists list

Because it’s all JSON, composing the catalog into other tools is trivial. Pull every collection name:

deadca7 collections list | jq -r '.[].name'

Or find tracks by a search term and grab their titles and BPMs:

deadca7 contents list "808" | jq -r '.[] | "\(.title)\t\(.bpm)"'

The same operations are available directly over the JSON REST API if you’d rather skip the binary — /api/imports, /api/collections, /api/collections/{id}/playlists, /api/playlists/{id}/contents, /api/contents?search=..., and /api/artists. The CLI is a convenience over these routes, not a separate system.

Hand it to an agent

This is where JSON-first pays off twice. deadca7 ships an agent SKILL: a description of these commands that a coding agent can read and act on. Because the CLI emits structured output and signals failure with stable exit codes, an agent can run a command, parse the result, check whether it worked, and decide what to do next — without scraping human-readable text or guessing at errors.

So “import this netlabel, wait for it to finish, then make a collection of everything tagged drum and bass” becomes a task you can delegate. The agent runs the same imports create, imports get, and contents list you would, reads the JSON, and chains the steps. Everything you can do by hand, an agent can do for you — that’s not a separate feature, it’s just what falls out of building the CLI this way.

The throughline

The CLI is the ownership argument made operational. Your collections are yours to take anywhere, exportable to your gear, and the API over them is documented and scriptable end to end. No export button to beg for, no automation tier to unlock — just commands and JSON.

Start with the getting started guide to get a catalog running, then point the CLI at it. The features page covers the rest of what’s in the box.