rfcli ships with RenderFlow and covers the whole published API, one command per operation, generated from the same document as the SDKs, so nothing drifts and nothing is missing.
Where it is
It sits beside the service, in the installation folder, and it is not added toPATH:
Call it by its full path, or add that folder to
PATH yourself. Every example below writes rfcli for brevity.
Two things to set up
It needs an API key, always. Even on the machine running the service, where the REST API itself would answer without one:export line to ~/.bashrc or ~/.zshrc to keep it for every new terminal. When the key is missing or refused, rfcli prints these same steps for the platform it runs on.
It reaches a remote farm with an address. Without one it talks to the service on this machine:
--server beats RENDERFLOW_URL, and both beat this machine. The scheme rides on the address, exactly as it does everywhere else in RenderFlow, and each picks its own port: a bare host or http:// is the plaintext listener on 44442, https:// is the farm’s TLS listener on 44445. Name a port and that is the one used.
For a server behind a studio certificate authority:
--insecure accepts a certificate this machine does not trust, for a test farm with a self-signed certificate. It also accepts one that is not the farm’s, so keep it off a production farm.
The shape of every command
One id uses the route built for one; more than one uses the bulk route. They are the same sentence with a different number of nouns, and the CLI picks the endpoint.
--ids a,b,c is the same thing comma separated, for a list that came out of another command.
A flag is the document’s own field name, so it carries underscores: --pool_id, --node_id, --job_id, --max_batch_size. The dashed spelling is refused rather than ignored.
Names instead of ids
Pools, user groups, machines, jobs, users and licenses can be named wherever an id goes: as the subject of a command, and in--pool_id, --node_id, --job_id, --user_id, --whitelisted_nodes and --excluded_nodes. On users commands, --group_id takes a user group’s name as well.
Output
A terminal gets a table; a pipe gets JSON.127.3 GB and 18h 57m. A single document, such as rfcli jobs get <id>, prints one field per line, its steps as a small table, and every other list as a count, because a job’s assets can run to thousands. Empty fields are left out. jobs logs and tasks logs print the log lines themselves.
The JSON a pipe or --json gets is the API’s answer, unchanged: ids, every field, and timestamps in milliseconds.
Watching a read
--watch redraws every ten seconds, or every N. It works on reads only: watching a write would re-send it on every redraw, which would stop a job, start it, and stop it again for as long as the terminal stayed open. It also needs a terminal, so in a script you write the loop yourself.
Live view
rfcli live opens on jobs, and rfcli live nodes opens on machines. --fps caps how often the screen redraws, 8 times a second by default.
Every key runs the command it is named after, so
s on a job is exactly rfcli jobs stop <id>. A key that had its own code path would be a key that could drift from the command.
Administration
The farm’s logs, its statistics, maintenance mode, database backups and support bundles answer an API key, so an administrator can script them.
Restoring the database and deleting a backup are not part of the published API. Do those in the app.
The logs page by time rather than by count. A page that has older entries says so and prints the
--before_at and --before_id values that ask for the next one:
Exit codes
A command that fails prints its error and leaves with a non-zero code, which is the part that matters in a pipeline:rfcli jobs get $id && publish must not publish when that job is gone.
8 and 9 are separate on purpose: a launcher can tell “ask this person for a key” from “the key they gave is wrong”, and those need different dialogs.
Submitting from the command line
jobs create takes the request body as JSON:
--data is there as well for the shapes a flag cannot express:
--data merges over the flags rather than under them, so reaching for it never means fighting a flag you did not set.
Recipes
Requeue everything that failed on one machine, then take the machine out:rfcli service alive is the cheapest possible check that a farm is up, and it is the one route that answers without a credential, so it tells you about the farm rather than about your key.