Skip to Content

The command line

Rookery's commands by what they do. Each one is a call of the server's API, so a script does what the screens do.

A command is written rookery THING ACTION [NAME] [FLAGS], such as rookery host show studio or rookery secret set github. A few that you type often have a short form. rookery --help lists the things, and rookery THING --help lists what each can do. The command reference has every command with its flags.

Short formMeans
rookery lsrookery host list
rookery apply HOSTrookery host apply HOST
rookery exec HOST -- COMMAND…Run a command on the host
rookery ssh HOSTA shell over plain SSH
rookery run HOST ACTIONRun one of the host's actions
rookery ui [HOST]Open the screens
rookery serverookery server run

rookery alone prints a short help. A word Rookery doesn't know stops with status 2 and the command it was likely meant to be.

Which server

Each command calls the API of a Rookery server. Rookery picks the first of these:

  1. --server URL on the command line.
  2. ROOKERY_SERVER in the environment.
  3. The server that rookery login kept.
  4. The rookery serve of this machine, on its socket.
  5. A server inside Rookery itself, with this machine's installation. This one is on Linux alone.
rookery login https://rookery.example.ts.net   # asks for a setup key, then keeps the server and its token
rookery logout                               # forgets them again

The token comes from a setup key, from --token-file FILE or from --token-stdin. It never goes on the command line, where other users of the machine could read it. A command can also use a server once: rookery --server URL --token-file FILE ls.

Hosts

Output of rookery ls with three hosts
WhatCommand
See the hostsrookery ls
See the type, address, state and actions of one hostrookery host show studio
Describe a new host and install itrookery host create studio
Make the host with a provisionerrookery host create studio --provisioner ovh-incus
Take in a machine that existsrookery host add build-vm 192.0.2.40 --user ops
Change a settingrookery host set studio hostname=studio-2
Edit the profile in $EDITORrookery host edit studio
Save and load the profile as JSONrookery host export studio > studio.json, rookery host import studio studio.json
Apply the profilerookery apply studio
Bring every host that is behind up to daterookery rollout (Updates)
Rename a hostrookery host rename studio attic (Renaming a host)
Take over a host from the profile it keepsrookery host adopt studio 192.0.2.40 (Moving a host)
Start or stop a hostrookery host start studio, rookery host stop studio (Starting and stopping)
Save a copy of a host under another namerookery host duplicate studio attic (Duplicating a host)
Forget a hostrookery host remove studio
Forget it and destroy the machine its provisioner maderookery host remove studio --destroy

rookery host create asks what it needs to know when you're at a terminal. These are the questions of the set-up tabs of the screens, and the same rules check the answers. Each question has a flag. A script gives the answers with them:

rookery host create studio --method cloud-seed --set operator_username=ops \
  --set hostname=studio --feature github/cli --generate-passwords

rookery host create --help lists every key of --set. With --no-input, or without a terminal, a missing answer stops with status 2 and names its flag.

Installing

WhatCommand
Write the cloud seedrookery host seed studio > user-data, or --file user-data
Build the USB installerrookery host iso studio, with --write /dev/sdX to write it to a drive
Install Rookery's controller alonerookery run build-vm install-controller (Host types)
Change the type a profile saysrookery host set build-vm type=managed
Make a server a node, for Incus and Docker machinesrookery host add big 192.0.2.20 --user root --type node (Nodes)
Install Rookery's key on a hostrookery key trust build-vm (First contact)
Check the host's SSH host key, or accept a changed onerookery host verify studio, rookery host verify studio --accept
The passwords Rookery made for the accountsrookery host credentials studio

For a host whose sudo takes a password, Rookery asks for it at the terminal, once in a command, and keeps it only while the command runs. A script gives it with --sudo-password-stdin, which every command takes, or keeps it as the secret sudo/HOST. A rookery serve asks for it on its own terminal when it starts, or takes the kept secret.

Jobs

What changes a host runs as a job of the server, such as an apply or a roll-out. Rookery follows the job with a line that shows the step it is at and the last lines of its log, and ends with one line that says how it went. Ctrl+C stops following. The job goes on in a rookery serve.

WhatCommand
Start a job and leave it runningrookery apply studio --detach, which needs a rookery serve
See the jobsrookery job list
See some of themrookery job list --host studio, --subject provisioner:NAME or --running
See the page afterrookery job list --before ID, with the last job of the page before
See one jobrookery job show ID
Read its log, and go on as it writesrookery job logs ID -f
Wait for it, and take its statusrookery job wait ID

Actions

Output of rookery action list studio, with the actions of studio and whether each can run now
rookery action list studio                     # what the host can do
rookery run studio status                      # run an action; its exit status is rookery's
rookery run studio backup:restore snapshot=latest -y
rookery run studio github:login                # a sign-in runs in your terminal

An action's arguments are NAME=VALUE words, and -y answers its question. A required argument you leave out is asked for at a terminal. rookery action list lists Rookery's own actions beside the controller's, such as install-controller, and says why one can't run now. A host whose type is ssh has none of its controller's yet.

Sessions and commands

rookery exec studio -- id                      # as the agent
rookery exec studio --user root -- journalctl -u rookeryd -n 20
rookery session attach studio                  # a new shell as the agent
rookery session list studio
rookery session logs studio ID --tail 50 -f
rookery ssh studio                             # plain SSH as the SSH user
Output of Rookery exec studio -- id, showing the agent account

rookery exec ends with the command's own exit status. Its session is removed afterwards, unless --keep is given. Ctrl+Q leaves an attached terminal running.

Output of Rookery session list studio with one running terminal session

Secrets, registries and keys

WhatCommand
Keep a secretrookery secret set github, which reads the value at a prompt or on standard input
Give it to a host as a variablerookery host set studio secret.github=GH_TOKEN
Give it to a host as a filerookery host set studio secret.backup=~/.config/backup/password:0600
Stop giving itrookery host set studio secret.github=
Add a registryrookery registry add nexus nexus https://nexus.example.com --user ci-user
Give its login to a hostrookery host set studio registry.nexus=on
See the keys of the key ringrookery key list (Keys)
Replace a key on the hosts that take itrookery key rotate rookery (Rekeying)
Output of rookery host show studio, with its secrets and registries

See Secrets and Registries.

Provisioners and resources

WhatCommand
See the provisionersrookery provisioner list
See the types the plugins bringrookery provisioner types
Register onerookery provisioner add ovh-incus incus/vm server=https://192.0.2.10:8443 (Provisioners)
See how it is and what it maderookery provisioner show ovh-incus
Change its settingsrookery provisioner set ovh-incus project=agents
See what provisioners maderookery resource list (Resources)
Make a deployment from a Compose filerookery resource create wiki --provisioner docker --spec compose.yaml (Deployments)
Give it a new Compose filerookery resource set wiki --spec compose.yaml
Read its logrookery resource logs wiki -f
Remove itrookery resource remove wiki

Plugins

WhatCommand
See the pluginsrookery plugin list
See what one bringsrookery plugin show github
Install onerookery plugin add @acme/rookery-plugin-tools, or a .tgz or folder of this machine, which is sent to the server
Check for newer versionsrookery plugin update --check
Update themrookery plugin update, then rookery rollout

Ports, services and messages

WhatCommand
Reach a port of a host from this machinerookery port forward studio 8080, or 8080:3000 for another local port
Call a service a plugin runsrookery service call studio notes/store list
Read a host's channel as it comesrookery channel listen studio
The messages the server took inrookery inbox list
Mark one done, or open againrookery inbox done studio ID, rookery inbox reopen studio ID
The server's key-value storerookery kv list NAMESPACE, rookery kv set NAMESPACE KEY JSON

The server of this machine

WhatCommand
Run itrookery serve, with --listen ADDRESS:PORT [--expose] for the network (rookery serve)
Make a setup key for the first userrookery server setup-key (A Rookery server)
The store and its keyrookery server store status, encrypt, rekey, decrypt, copy (The store)
The API documentsrookery server api openapi, asyncapi, operations (API)
The server's settingsrookery config list, rookery config set KEY VALUE
Update Rookery itselfrookery update (Updates)

In scripts

FlagWhat it does
-o jsonPrint the API's own JSON documents instead of tables. Errors go to standard error as JSON as well
--no-inputNever ask; a missing value stops with status 2 and names its flag
-yAnswer yes to every question
-qPrint only the result
--color neverPrint without colours, as NO_COLOR does
StatusMeans
0Done
1A job failed, or a host didn't answer
2The command line was wrong
3Refused. The role is too low, the host or the server can't do it now, or a question had the answer no
4The server couldn't be reached

rookery completion bash prints the completions of a shell. Source them from its start-up file:

echo 'source <(rookery completion bash)' >> ~/.bashrc
Edit on GitHub

Last updated on

On this page