crystl CLI

guild membership

A built-in `crystl` CLI that puts every part of the GUI on your shell path, and on the path of every agent running inside a crystl shard.

works withany CLI agentclaude codecodexantigravity cli
$ crystl gems
* sigmacontent      [diamond (Claude)]
  /Users/chris/Nextcloud/sigmacontent
  crystl            [diamond (Claude), opal]
  /Users/chris/Nextcloud/crystl

$ crystl shard create --gem crystl --crystal-name jade --prompt "add tests"
Created jade in crystl
  /Users/chris/Nextcloud/crystl
  $ claude 'add tests'

$ crystl wait pending --timeout 30
Bash (id=42, gem=crystl, shard=jade)

$ crystl approve 42
Decision sent

The crystl CLI ships inside Crystl.app. Install it from Help → install command line tool… (or Settings → General → Command Line Tool). One admin prompt, then crystl is on your PATH in every new shell. It talks to the running crystl over a loopback HTTP bridge using the bearer token at ~/.crystl-bridge-token; no environment variables to wire up.

Same surface as the GUI, plus a few primitives the GUI can't expose: an SSE event stream (crystl events), no-polling waits for approvals, questions, notifications, awaiting input, and idle agents (crystl wait), and shard creation that an orchestrator agent can call from inside a sibling shard. The surface keeps growing with the app: crystl doctor (diagnostics), resurrect (undo-close), shard rename (label your workers), gauntlet (a release-readiness crew), sidequest (pair two shards in a 1:1 chat, even across gems), hero/party, workbench, and history with per-turn token & model metadata. When you open a project, crystl seeds a short reference section into the gem's agent instruction files so any agent in any shard discovers it can coordinate with the rest of your workspace.

Why it matters

One install, every shell

Help → install command line tool… symlinks /usr/local/bin/crystl to the bundled binary. One admin prompt, then `crystl` works in any new terminal.

Agents coordinate across shards

crystl gems, shards, screen, send, and shard create let one agent inspect or drive a sibling shard. Orchestrators fan work out and watch it land without leaving the terminal.

Block on real events, not polls

crystl events streams the bridge's SSE log as JSON lines. crystl wait can block on approvals, ask-user prompts, notifications, awaiting-input states, or idle transitions. Ideal for scripts and agent workflows.

Discoverable to agents

On each gem open, crystl keeps a marker-bracketed CLI section in supported agent instruction files. It's idempotent, can seed the file when needed, and can be disabled in General settings.

Dive deeper in the CLI docs →

Ready to try it?

Create a free account and download crystl for macOS.

get started getting started guide →

Frequently asked questions

Where does the binary live?
Inside Crystl.app at Contents/Helpers/crystl. The install action symlinks /usr/local/bin/crystl to that path; manual install is sudo ln -sfh /Applications/Crystl.app/Contents/Helpers/crystl /usr/local/bin/crystl.
Does the CLI need a separate auth setup?
No. crystl writes a bearer token to ~/.crystl-bridge-token at launch (0600 permissions, regenerated each run). The CLI reads it automatically and sends Authorization: Bearer on every request.
Can I drive the bridge directly from curl or another language?
Yes. The CLI is a thin wrapper around http://127.0.0.1:19280/api/v1/. Endpoints, JSON shapes, and curl examples are in the CLI docs. Local loopback requests use the bridge token directly; non-loopback mutating requests require remote access to be enabled.
Does the agent snippet edit my instruction files every time?
Only when the marker-bracketed section would actually change. Re-opening with no diff is a no-op so git mtimes stay clean. The section can be removed to opt out one gem at a time, or you can flip the General settings toggle to opt out everywhere.
Does it work over SSH?
Yes. SSH shards can route notifications and CLI bridge calls back to your Mac. If the default reverse tunnel conflicts with the remote host, `crystl ssh bridge-address ` sets a direct bridge address for the next SSH connection.
Book of Spells
the crystl guild

Crystl's Book of Spells

Master crystl with a grimoire of powerful prompts. Summon heroes, assemble a party, revive shards, and complete epic quests.

open the book →

More features

Gems & Shards

Gems, shards, and the Crystal Rail keep every project one click away.

Action Panels

See what every Claude session is doing at a glance.

Parallel Sessions

Run multiple Claude instances on the same repo without conflicts.

Hero Shards

Summon a single hero as a shard — its own agent, model, and persona — without a quest party.

History Navigator

Browse, jump through, and search every session: conversation and tool calls.

Token Tracking

Track token burn per shard, estimate turns left, and reclaim context window by disabling heavy plugins and skills.

Workbench

A slide-out task list in every project, backed by a WORKBENCH.md the agent reads and writes with you.

Prompt Integration

Facet Inserts give you one-click access to saved prompts, commands, and shortcuts.

Agent Config Editor

Create, edit, and manage CLAUDE.md, rules, skills, and agent config files with a block editor, file chooser, and project optimizer.

Project Optimizer

Scan your project for gaps in agent configuration (missing files, incomplete docs, oversized code, and setup issues) with one-click fixes.

Starter Bundles

New gems launch with CLAUDE.md, rules, skills, and MCP config, all pre-configured from your bundle library.

Skills Library

Browse and import agentic skills that teach agents like Claude Code or Codex new tricks: code review, testing, deployment, and more.

Cavrn

The terminal as structured data: every turn, tool call, result, and table captured as agent-readable metadata. Drawn fast on the GPU with Metal.

Remote Development

Full crystl integration over SSH: approval panels, file relay, and click-to-open on remote machines.

Agent Orchestration

One agent spawns, supervises, and merges the work of many: a control room for a team of coding agents.

crystl Quest

Assemble a party of specialized agents. Each brings unique skills, coordinates in shared chat, and executes in parallel.

Screenshot Bar

Drag recent screenshots into the terminal. Spotlight-powered, always up to date.

Copy Bar

A one-click copy bar under the terminal. Agents stage text, you click Copy. Editable, up to 10 tabs, free.