Driving DevThrottle from a script

Everything the Director does, something else can do too. There is a command line, and it serves a person typing and a program asking equally well - the fleet commands go through your Gateway. This is what you reach for when you want DevThrottle to act while nobody is watching.

Fifteen minutes, and you should be comfortable on a command line. You need DevThrottle running with a Gateway - and run the commands from inside a DevThrottle session, the easiest place being any agent you already have open. A session's environment carries the Gateway address and the session's own key (CC_GATEWAY_URL and CC_GATEWAY_SESSION_KEY); in a plain terminal without that pair, the fleet commands stop and tell you they only work inside a session. Export the pair if you want them from your own terminal.

1. See your fleet from a terminal

   The command line is installed with DevThrottle - there is nothing extra to fetch. Start with the one that just reads:

   What is running right now

   cc-devthrottle session list

   That is the same fleet the Director shows you, as text. If this works, everything else in this tutorial will.

2. Check your own setup

   Is everything wired up

   cc-devthrottle setup status

   Useful as the first line of any script you write, and the first thing to run when a script that used to work stops working.

3. Send a message to a session

   An agent can be told something without you opening its window:

   Say something to a running session

   cc-devthrottle message send <session> "the build is red, look at that first"

   Warning

   This interrupts the agent you send it to, exactly as if you had typed it. That is fine when you mean it and disruptive when you did not - be careful sending to more than one at a time.

4. Let a program ask

   The fleet commands above work unchanged inside a script, because of how they are wired: a fleet call goes to your Gateway, carrying the calling session's own key. Not every command needs that - setup status and the catalog below are local and run in any terminal - but everything that reads or drives the fleet does. There is no local address to discover and no port on the Director - it does not have one, by design. A program that should not guess what it may run can ask for the whole catalog in JSON:

   Every action, machine-readable

   cc-devthrottle actions --json

   Each entry names the command, its arguments, and whether it changes anything (mutatesState), so a script can stick to the reads. How calls are authorized - the session key, and what it may and may not do - is on the Control API reference, which stays the single source of truth for that.

5. Put it on a schedule

   Once a script does something useful, the thing you usually want is for it to happen without you. That is the Gateway's job rather than your operating system's, and creating a schedule is one command - name it, say which machine and folder the session runs in, when, and what it should do:

   Every weekday at 06:00, run the tests

   cc-devthrottle schedule create --name "nightly tests" --machine YOUR-PC --repo D:/repos/my-project --cron "0 6 * * 1-5" --tz "Europe/Copenhagen" --seed "Run the test suite and fix what is red."

   What is scheduled now

   cc-devthrottle schedule list

   Use your own machine name (cc-devthrottle session whoami prints it) and your own time zone. For a one-off instead of a recurring job, swap --cron for --at with a local timestamp. For doing the same from a screen, and what every field means, see Work that runs without you.

Next

For every shipped command and what each one does, see the command reference. For how fleet calls are authorized, the Control API. For the model API, the API overview.