CLI tool reference

Reference for the command-line tools the DevThrottle installer puts on your PATH. They exist so your agents (and you) have a reliable, pre-installed way to produce documents, send email, work with images, keep a personal knowledge vault, let an agent use a password it never sees, and drive the DevThrottle fleet itself. Nine tools ship; nothing else is listed here. Every tool answers --help with its full command list.

Document conversion: cc-pdf, cc-html, cc-word

Three converters that turn a Markdown file into a finished document - and read a finished document back to Markdown. They share the same two commands, the same option style, and the same theme set, so learning one is learning all three.

cc-pdf from-markdown input.md -o output.pdf --theme boardroom
cc-html from-markdown input.md -o output.html --theme paper
cc-word from-markdown input.md -o output.docx --theme boardroom
cc-pdf from-markdown input.md -o output.pdf --page-size a4 --margin 1in
cc-pdf to-markdown report.pdf -o report.md

• from-markdown - Markdown in, finished document out. to-markdown - the other direction, extracting the document's embedded images as it goes.
• -o - output file path. Required on from-markdown; on to-markdown it defaults to the input name with a .md extension.
• --theme - document style, paper by default (see themes below).
• --page-size - a4 (the default) or letter (cc-pdf only).
• --margin - page margin, 1in by default (cc-pdf only).
• --css - a custom CSS file to style the output (cc-pdf and cc-html).
• --strict-assets - fail instead of carrying on when a local image cannot be embedded (cc-pdf and cc-html).
• --force overwrites an existing output file, --no-clobber skips instead, and --quiet suppresses progress without hiding errors.

The shared themes, from cc-pdf --themes:

• boardroom - corporate, executive style with serif fonts; the pick for professional reports.
• paper - minimal and clean (the default).
• terminal - technical, monospace.
• blueprint - technical documentation.
• thesis - academic.
• spark - creative, colorful.
• obsidian - dark theme.

cc-devthrottle

The fleet command surface: talk to your running sessions, the machines they run on, and the Gateway that holds them together - the same tool your agents use to message each other. The fleet commands call the Gateway with the calling session's own key; every session launched by a Director attached to a Gateway carries that credential in its environment (CC_GATEWAY_URL and CC_GATEWAY_SESSION_KEY) - so run them from inside such a session, or export that pair in a plain terminal first. A local-only Director stamps neither, and the commands say so. Local commands such as setup status and actions work anywhere.

cc-devthrottle session list
cc-devthrottle message send <id> "message"
cc-devthrottle session workers
cc-devthrottle schedule list
cc-devthrottle setup status

Sixteen command groups plus two top-level commands, each with its own --help:

• session - the sessions themselves: list, whoami, rename, prompt, interrupt, raise, workers, report, hold, compact, compact-continue, buffer, role, done, stop, spawn.
• message - send a message to another session, or ask and wait for its answer (see fleet messaging).
• mission - the unit of work sessions attach to: create, list, rename, complete, remove, reopen, attach, detach.
• director - list every Director this account is running, with the id to pass to session spawn --director.
• machine - the computers you can reach: list, apps, files, launch, and asking for a Director restart - restart-capability (whether that machine can complete one; changes nothing), restart-request (ask, with a reason the owner accepts once) and restart-request-status (see machines).
• repo - list the fleet's repositories with their state and worktree summary.
• worktree - list the fleet's worktrees, their sizes, and which session is in each.
• workflow - read and author fleet workflows: list, show, instructions, versions, pull, push, publish, materialize, runs, run, enable, disable, clone, delete.
• skill - the same shape for fleet skills: list, get, show, versions, pull, push, publish, clone, enable, disable, delete.
• schedule - list, get, create, run, enable, disable, delete, plus runs and endpoint (see scheduled runs).
• browser - DevThrottle's drivable browser profiles, signed in once by hand and then driven by an agent: list, create, signin, start, stop, attach, rename, remove. Machine-local.
• diag - network (per connected device: direct or relayed, latency, UDP and NAT) and results (recent speed tests submitted from the app or the Cockpit); see network.
• autostart - on, off, status for starting the Gateway at login.
• email - owner sends one email to the account owner, and there is no way to address anyone else.
• settings - read and write Director settings: show, get, set, list, path.
• setup - status, install, update, repair, doctor.
• selftest - run the fleet-messaging self-test against the local Director.
• actions - list the agent-discoverable actions.

Two of the session commands are how a session asks for help when nobody is watching it. session raise puts a session's hand up to whichever session is driving it - a worker to its manager, say - with a line saying what it is blocked on; the hand comes down when that session's turn ends, or on --clear. session workers is the other end of the same channel: it lists the sessions you are driving and which of them have their hand up. They exist because a supervised session is quiet toward you by design, and it still needs somewhere to put a question it cannot answer itself. session report is the last step of delegated work: when a session's turn ends, it tells the session that owns it what it did, in its own words.

Two commands end a session. session done is the polite one: it flags a session for deletion and its Director removes it once it is no longer working (--undo takes the flag back off). session stop ends it now - it stops the agent process on the machine that owns the session and removes the session - and it requires --reason, which is recorded with the stop. Neither touches files: uncommitted changes in the session's worktree are left as they were.

workflow and skill are the command-line windows onto two Gateway-held libraries, and each has its own page: workflows for how a whole job is run and who staffs it, skills for the individual capabilities an agent picks up in the middle of one. Both follow the same rule - push uploads a private draft that no agent sees, and publish is what makes it live fleet-wide.

Email: cc-gmail and cc-outlook

Read, search, send, and manage email from the command line - one tool per provider, with matching command styles. Both authenticate once (auth) and then work non-interactively, which is what makes them usable by agents.

cc-gmail list
cc-gmail search "from:someone@example.com"
cc-gmail send --to someone@example.com --subject "Hi" --body "..."
cc-outlook list
cc-outlook reply <id> --body "..." --send

• Shared commands: auth, list, read, send, draft, reply, search, delete, archive, move, recipients, profile.
• reply saves a draft unless you pass --send; --all replies to everyone, and --html marks the body as HTML on both send and reply.
• cc-gmail adds drafts, count, untrash, archive-before, labels (labels, label-stats, label-create), and a mailbox stats dashboard; searches use Gmail query syntax.
• cc-outlook adds forward, flag, categorize, unarchive, attachments, download-attachment, and folders/create-folder; auth is Device Code Flow.
• Both go beyond the inbox: calendar on each, and contacts on cc-gmail.
• Both take --account to pick between signed-in accounts, and accounts to manage them.

cc-image

Image toolkit: AI description and text extraction plus local resize and format conversion. By default the AI commands run through the DevThrottle API with your dt_ key (--engine picks another engine); the local commands need no key at all.

cc-image describe photo.png
cc-image ocr scan.png
cc-image resize big.png -o small.png --width 800
cc-image convert image.png -o image.webp

• describe / ocr - AI analysis and text extraction, single image or whole folders (batch cataloging to JSON/CSV with resume). The default engine requires DEVTHROTTLE_API_KEY.
• resize / convert / info - local, keyless image operations.
• Images are downscaled before AI analysis, so bulk runs stay cheap.

cc-vault

A personal knowledge vault - contacts, tasks, goals, ideas, health notes, posts, and documents - with semantic search and ask-a-question retrieval over everything in it. Your vault's data is stored on this machine. Search and ask both use an outside model service, in different ways: search sends only your query, to turn it into a search vector, and then searches the stored vectors on this machine; ask also sends the vault content it retrieved, so the service can write the answer. Building those stored vectors in the first place - adding or re-indexing documents - sends the text being indexed to the same service. All of it needs a key you supply and pay for, set as OPENAI_API_KEY. cc-vault config show prints whether it is set, and without it those two commands stop rather than quietly returning something weaker.

cc-vault init
cc-vault search "kickoff meeting notes" --hybrid
cc-vault ask "what did we decide about pricing?"
cc-vault tasks add "Follow up with the pilot customer"
cc-vault backup

• Entities: contacts, tasks, goals, ideas, docs, health, posts - each its own group of commands such as add, list, show and update (health only reads: list and insights).
• Organising them: lists and tags for contacts, library and catalog for documents, graph for statistics and traversal.
• Retrieval: search (semantic, with --hybrid to add keyword matching and --type to narrow it) and ask (question answering over the vault).
• Connecting things: link, unlink, links, and context, which returns an entity together with everything linked to it - the shape an agent wants.
• Care and feeding: stats, config show, backup, restore, and repair-vectors to rebuild the search index from the stored text.

cc-secrets

Lets a session use a password without the model ever seeing it. You add an entry by hand from your own terminal - never through a session - and a session asks the tool to run a command with the password supplied, or to fill a login form in a browser profile the Director owns. The tool hands back only the result, and every use goes in an audit log. It protects against accidental exposure - transcripts, logs, output, screenshots - not against a hostile program running as the same user. The full guide, including where the store lives and the limits, is cc-secrets.

cc-secrets add devlinux
cc-secrets list
cc-secrets run devlinux -- sudo -S apt-get update
cc-secrets login github-work --browser center-consulting
cc-secrets log

• Owner commands, run from your own PowerShell or cmd window and refused inside a session: add, remove, list --all.
• Session commands: list, run (the password on standard input, in an environment variable, or through an askpass helper), and login (a Director-owned browser profile, on an allowed address only).
• Anyone: log and version.
• The store works on Windows and Linux. On macOS the store is not supported yet, so no entry can be added or used there.