Docs/Tutorials/Driving it from a script
Tutorials

Driving DevThrottle from a script

8 min read

Everything the board does, something else can do too. There is a command line for the things you would type, and an HTTP interface for the things a program would ask. 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.

  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 board 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. Ask over HTTP instead

    For anything that is not a person at a keyboard, each Director exposes an HTTP interface on your own machine, and every call carries a token. The full list of what you can ask it - reading sessions, sending a prompt, queueing one, interrupting - is on the Control API reference, which stays the single source of truth for those shapes.

    The pattern is always the same: a local address, a bearer token, JSON in and JSON out.

  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:

    What is already scheduled
    cc-devthrottle schedule list

    See Work that runs without you for setting one up.

Note
There is a separate, larger API for talking to models rather than to your fleet - that is the DevThrottle API, and it is a different thing from the Control API used above. Fleet control is local and about your sessions; the model API is a hosted service and is billed.

Next

For every shipped command and what each one does, see the command reference. For the fleet HTTP interface, the Control API. For the model API, the API overview.