Skip to Content

Command reference

Every command of rookery with its arguments, made from the same definition as rookery --help.

This page is generated from the commands themselves. The command line explains them by what they do.

Flags of every command

FlagWhat it does
--server URLUse this rookery server for this command: https://HOST, http://HOST:PORT or unix:/path. rookery login keeps one.
--token-file FILERead the server's token from this file.
--token-stdinRead the server's token from standard input.
-o, --output OUTPUTWhat is printed on standard output: a table for people, or the API's own JSON. One of table, json. By default table.
--no-inputNever ask. What is missing is an error that names the flag to pass.
-y, --yesAnswer yes to a confirmation.
-q, --quietPrint only the result.
--sudo-password-stdinRead the SSH user's sudo password from standard input, for a host whose sudo asks for one.
--color WHENColours: on a terminal, always or never. NO_COLOR turns them off as well. One of auto, always, never. By default auto.

Flags go before or after the names, as --tail 50 or --tail=50. -- ends the flags; what follows it is passed on as it is.

Exit statuses

StatusMeans
0done
1the work failed: a job failed, or a host did not answer
2the command line was wrong: an unknown word, a missing value, a bad flag
3refused: the role is too low, the host or this server cannot do it now, or a confirmation was declined
4the server could not be reached

A command run on a host, such as rookery exec, ends with that command's own status.

Environment

VariableWhat it does
ROOKERY_SERVERThe server, when no --server is given. It wins over the one rookery login kept.
ROOKERY_TOKENIts token, when no --token-file or --token-stdin is given. For containers and CI.
NO_COLORNo colours, as --color never.
ROOKERY_ and a setting's nameA setting of the server, in capitals, such as ROOKERY_RETENTION_DAYS, for a server in a container.
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_RUNTIME_DIRWhere rookery keeps its settings, its data and its socket.
VISUAL, EDITORThe editor of rookery host edit.

rookery ls

Short for rookery host list.

rookery ls

rookery apply

Short for rookery host apply.

rookery apply NAME [--detach]
ArgumentWhat it is
NAMEIts name.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery exec

Run a command on a host and pass its exit status through.

rookery exec HOST [--user USER] [--detach] [--keep] -- COMMAND…
ArgumentWhat it is
HOSTA host's name.
--user USERThe account it runs as: agent, operator or root. By default agent.
--detachStart it and return; rookery session logs HOST ID shows what it writes.
--keepKeep the session once it has ended, for rookery session logs.
COMMAND…The command and its arguments, after --.

rookery ssh

A shell on a host over plain SSH, or a command run there. Needs the installation on this machine.

rookery ssh HOST [--agent] [-- COMMAND…]
ArgumentWhat it is
HOSTA host's name.
--agentLog in as the agent account.
COMMAND…A command to run there, after --.

rookery run

Run one of a host's actions: rookery action list HOST names them.

rookery run HOST ACTION [NAME=VALUE…] [--detach]
ArgumentWhat it is
HOSTA host's name.
ACTIONThe action's name.
NAME=VALUE…The action's arguments.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery ui

Open rookery's screens: the home screen, or the page of one host.

rookery ui [HOST]
ArgumentWhat it is
HOSTThe host to open.

rookery host

The hosts: list, create, add, change, install and remove them.

rookery host list

The hosts, with their address and whether each answers.

rookery host ls is the same.

rookery host list

rookery host show

One host: its type, address, state and actions.

rookery host show NAME
ArgumentWhat it is
NAMEIts name.

rookery host create

Describe a new host, then install it. Asks what is missing on a terminal.

rookery host create NAME [--method METHOD] [--from PROFILE] [--type TYPE] [--feature FEATURE] [--no-feature FEATURE] [--set KEY=VALUE] [--generate-passwords] [--provisioner PROVISIONER] [NAME=VALUE…] [--run] [--detach]
ArgumentWhat it is
NAMEIts name.
--method METHODHow it is installed: provisioner, iso, cloud-seed, ssh or ssh-only.
--from PROFILEStart from a profile: a host's name, a JSON file, or - for standard input.
--type TYPEWhat rookery does with it: workstation, or node for a server of machines, applied over SSH.
--feature FEATURESwitch on a plugin's feature, PLUGIN/FEATURE. Again for more.
--no-feature FEATURESwitch off a plugin's feature.
--set KEY=VALUESet a field of the profile. Again for more; the keys are listed below.
--generate-passwordsGenerate the accounts' passwords; rookery host credentials NAME shows them.
--provisioner PROVISIONERMake the machine with this provisioner, which also sets it up.
NAME=VALUE…The provisioner's arguments, such as cpus=2.
--runInstall it once it is saved: apply, render the seed or build the installer.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

The ways to install, for --method:

MethodWhat it is
provisionerFrom a provisioner
isoUSB installer
cloud-seedCloud-init seed
sshExisting host over SSH
ssh-onlyExisting host, SSH only

The fields of a profile, for --set KEY=VALUE here and rookery host set. A switch takes on or off. feature.PLUGIN/FEATURE=on, secret.NAME=VARIABLE and registry.NAME=on give a host those as well.

KeyField
typeType
targetTarget
addressSSH address
userSSH user
portSSH port
authLog in with
sudoAsk for sudo password
power_stopStopped by
hostnameHostname
install_tailscaleTailscale
tools_webJavaScript runtimes
tools_nativeNative development
tools_jvmJVM development
tools_dotnet.NET development
tools_scriptingScripting languages
tools_scientificScientific computing
tools_chromeGoogle Chrome
install_playwrightPlaywright
software_renderingSoftware graphics
install_cockpitCockpit web console
install_dockerDocker on host
operator_usernameOperator username
operator_ssh_public_keysSSH key
operator_password_hashOperator password hash
agent_usernameAgent username
agent_password_hashAgent password hash
agent_ssh_public_keysSSH key
agent_privilegesAgent privileges
agent_passwordless_sudoAgent passwordless sudo
harden_sshSSH hardening
bootstrap_ssh_cidrRecovery SSH CIDR
geometryDesktop size
target_disk_modeDisk selection
target_disk_serialTarget disk serial
target_disk_modelDisk model pattern
target_disk_pathDisk path pattern
target_disk_ssdDisk type filter
keyboardKeyboard layout
wifi_enabledWi-Fi
wifi_ssidWi-Fi SSID
wifi_passwordWi-Fi password
wifi_interfaceWi-Fi interface
release_storePublish release to
release_urlRelease HTTPS URL
release_privateDownload with login
isoSource ISO
iso_sha256ISO SHA256
usb_deviceThen write to USB drive
inventoryAnsible inventory

rookery host add

Take in a machine that exists, by its address, and log in to it once.

rookery host add NAME ADDRESS [--user USER] [--port PORT] [--auth AUTH] [--type TYPE] [--feature FEATURE] [--no-contact] [--password-stdin]
ArgumentWhat it is
NAMEIts name.
ADDRESSIts name or IP address, or a Host alias of the server's SSH configuration.
--user USERThe account rookery logs in as.
--port PORTIts SSH port, when not 22.
--auth AUTHHow rookery logs in: rookery, key:NAME, password or ssh.
--type TYPEWhat rookery does with it: ssh, managed, node or workstation. By default ssh.
--feature FEATURESwitch on a plugin's feature of a node or a workstation, PLUGIN/FEATURE, such as incus/server. Again for more.
--no-contactSave it without logging in to it.
--password-stdinRead a password from standard input that installs rookery's key on it, once.

rookery host set

Change settings of a host's profile: KEY=VALUE, as rookery host create --help lists the keys.

rookery host set NAME KEY=VALUE…
ArgumentWhat it is
NAMEIts name.
KEY=VALUE…KEY=VALUE, where KEY is a field (rookery host create --help), feature.PLUGIN/FEATURE, secret.NAME or registry.NAME.

rookery host edit

Change a host's profile in $EDITOR.

rookery host edit NAME
ArgumentWhat it is
NAMEIts name.

rookery host export

A host's profile as JSON on standard output.

rookery host export NAME
ArgumentWhat it is
NAMEIts name.

rookery host import

Save the profile in FILE (- for standard input) as the host's, new or changed.

rookery host import NAME FILE
ArgumentWhat it is
NAMEIts name.
FILEThe profile as JSON, such as rookery host export wrote; - for standard input.

rookery host apply

Apply the host's profile to it over SSH, or install its controller alone when it is managed.

rookery host apply NAME [--detach]
ArgumentWhat it is
NAMEIts name.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery host seed

The cloud-init user data that installs the host on first boot, on standard output.

rookery host seed NAME [--file FILE]
ArgumentWhat it is
NAMEIts name.
--file FILEWrite it to FILE instead.

rookery host iso

Build the host's unattended USB installer where the server runs, and write it to a drive.

rookery host iso NAME [--write DEVICE] [--password-stdin] [--detach]
ArgumentWhat it is
NAMEIts name.
--write DEVICEWrite it to this USB drive, which is erased, such as /dev/sdb.
--password-stdinRead your sudo password for writing the drive from standard input.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery host rename

Give a host another name in rookery. The machine is left as it is.

rookery host rename NAME NEW [--hostname]
ArgumentWhat it is
NAMEIts name.
NEWIts new name.
--hostnameMake NEW its profile's hostname as well, and its device's name on the tailnet, for the next apply.

rookery host remove

Forget a host. The machine is left as it is, unless --destroy.

rookery host rm is the same.

rookery host remove NAME [--destroy]
ArgumentWhat it is
NAMEIts name.
--destroyDestroy the machine a provisioner made for it as well, with its disk, and remove its device from the tailnet.

rookery host duplicate

Save a copy of a host's profile as the host NEW, without what belongs to its machine. No disk is cloned.

rookery host duplicate NAME NEW [--create] [--detach]
ArgumentWhat it is
NAMEIts name.
NEWThe copy's name.
--createHave the provisioner that made NAME make NEW's machine at once.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery host adopt

Take in a host rookery set up before, from the profile it keeps.

rookery host adopt NAME [ADDRESS] [--port PORT] [--key FILE] [--force] [--detach]
ArgumentWhat it is
NAMEIts name.
ADDRESS[USER@]ADDRESS; without it, the saved host of that name.
--port PORTIts SSH port, when not 22.
--key FILEA private key file where the server runs, offered as well for reading the profile only.
--forceReplace a host of that name.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery host credentials

The passwords rookery generated for a host's accounts.

rookery host credentials NAME [--show]
ArgumentWhat it is
NAMEIts name.
--showPrint them even when standard output is no terminal.

rookery host verify

Check the host's SSH host key, and accept a new one.

rookery host verify NAME [--accept]
ArgumentWhat it is
NAMEIts name.
--acceptAccept the key the host shows now.

rookery host start

Start a host, through the provisioner that made it.

rookery host start NAME [--detach]
ArgumentWhat it is
NAMEIts name.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery host stop

Stop a host: through the provisioner that made it, or as its profile's power.stop says.

rookery host stop NAME [--detach]
ArgumentWhat it is
NAMEIts name.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery host inventory

The hosts as an Ansible inventory. Needs the installation on this machine.

rookery host inventory [NAMES…]
ArgumentWhat it is
NAMES…The hosts; all with an address when none is named.

rookery rollout

Bring the hosts up to date, one at a time.

rookery rollout [--only HOST] [--except HOST] [--all] [--update] [--reboot] [--force] [--detach]
ArgumentWhat it is
--only HOSTOnly these hosts. Again for more.
--except HOSTLeave these hosts out. Again for more.
--allTake hosts that are up to date as well.
--updateRun each host's update action as well.
--rebootReboot the hosts that need it, unless sessions run there.
--forceWith --reboot: even when sessions run.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery action

What a host can do.

rookery action list

What a host can do, or the installation without a host.

rookery action ls is the same.

rookery action list [HOST]
ArgumentWhat it is
HOSTA host's name.

rookery session

The terminal and process sessions of a host.

rookery session list

A host's sessions, running and ended.

rookery session ls is the same.

rookery session list HOST
ArgumentWhat it is
HOSTA host's name.

rookery session attach

This terminal onto a terminal session, or onto a new shell as the agent. Ctrl+Q leaves it running.

rookery session attach HOST [ID]
ArgumentWhat it is
HOSTA host's name.
IDIts id.

rookery session logs

What a session wrote.

rookery session logs HOST ID [-f, --follow] [--tail N]
ArgumentWhat it is
HOSTA host's name.
IDIts id.
-f, --followGo on as it writes more.
--tail NOnly the last N lines.

rookery session stop

End a session.

rookery session stop HOST ID
ArgumentWhat it is
HOSTA host's name.
IDIts id.

rookery provisioner

What can make hosts and resources, such as Incus or Docker.

rookery provisioner list

The provisioners, and whether each can be used here.

rookery provisioner ls is the same.

rookery provisioner list

rookery provisioner types

The types of provisioner the plugins bring.

rookery provisioner types

rookery provisioner add

Register a provisioner of a type, such as incus/vm, under a name of its own.

rookery provisioner add NAME TYPE [NAME=VALUE…]
ArgumentWhat it is
NAMEIts name.
TYPEIts type, as rookery provisioner types lists them.
NAME=VALUE…Its settings.

rookery provisioner show

How it is now and what it holds. NAME=VALUE gives one of its settings another value for this once.

rookery provisioner show NAME [NAME=VALUE…]
ArgumentWhat it is
NAMEIts name.
NAME=VALUE…A setting with another value for this once.

rookery provisioner set

Change its settings.

rookery provisioner set NAME NAME=VALUE…
ArgumentWhat it is
NAMEIts name.
NAME=VALUE…A setting and its new value.

rookery provisioner rename

Give a provisioner another name in rookery, with its settings, secrets and what it made.

rookery provisioner rename NAME NEW
ArgumentWhat it is
NAMEIts name.
NEWIts new name.

rookery provisioner remove

Forget a provisioner that holds nothing.

rookery provisioner rm is the same.

rookery provisioner remove NAME
ArgumentWhat it is
NAMEIts name.

rookery provisioner actions

What it can do.

rookery provisioner actions NAME
ArgumentWhat it is
NAMEIts name.

rookery provisioner run

Run one of its actions.

rookery provisioner run NAME ACTION [NAME=VALUE…] [--detach]
ArgumentWhat it is
NAMEIts name.
ACTIONThe action's name.
NAME=VALUE…The action's arguments; a required one that is missing is asked for.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery resource

What provisioners made that is not a host, such as a deployment.

rookery resource list

What provisioners made.

rookery resource ls is the same.

rookery resource list [--kind KIND] [--provisioner PROVISIONER] [--host HOST]
ArgumentWhat it is
--kind KINDOnly those of this kind, such as deployment or machine.
--provisioner PROVISIONEROnly those this provisioner made.
--host HOSTOnly the machine of this host.

rookery resource show

One of them as its provisioner says it is now.

rookery resource show ID
ArgumentWhat it is
IDIts id.

rookery resource create

Make a resource, such as a deployment from a Compose file.

rookery resource create NAME --provisioner PROVISIONER [--kind KIND] [--spec FILE] [--secret NAME[:VARIABLE]] [NAME=VALUE…] [--detach]
ArgumentWhat it is
NAMEIts name.
--provisioner PROVISIONERThe provisioner that makes it.
--kind KINDIts kind, where the provisioner makes several.
--spec FILEThe specification, such as a Compose file; - for standard input.
--secret NAME[:VARIABLE]A secret it gets, NAME or NAME:VARIABLE. Again for more.
NAME=VALUE…The arguments of its kind.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery resource set

Change a resource: other arguments, a new specification, other secrets.

rookery resource set ID [--spec FILE] [--secret NAME[:VARIABLE]] [NAME=VALUE…] [--detach]
ArgumentWhat it is
IDIts id.
--spec FILEA new specification; - for standard input.
--secret NAME[:VARIABLE]The secrets it gets from now on, NAME or NAME:VARIABLE. Again for more.
NAME=VALUE…Arguments with new values.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery resource remove

Remove a resource with its provisioner.

rookery resource rm is the same.

rookery resource remove ID [--detach]
ArgumentWhat it is
IDIts id.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery resource logs

What it wrote.

rookery resource logs ID [-f, --follow] [--tail N]
ArgumentWhat it is
IDIts id.
-f, --followGo on as it writes more.
--tail NOnly the last N lines.

rookery resource exec

Run a command in it, for a kind that has exec, and exit with its exit status.

rookery resource exec ID [--stdin] -- COMMAND… [--detach]
ArgumentWhat it is
IDIts id.
--stdinGive the command what rookery reads on standard input, to its end.
COMMAND…The command and its arguments, after --.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery resource actions

What it can do.

rookery resource actions ID
ArgumentWhat it is
IDIts id.

rookery resource run

Run one of its actions.

rookery resource run ID ACTION [NAME=VALUE…] [--detach]
ArgumentWhat it is
IDIts id.
ACTIONThe action's name.
NAME=VALUE…The action's arguments; a required one that is missing is asked for.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery job

The work the server does: applies, installers, roll-outs.

rookery job list

The jobs, newest first.

rookery job ls is the same.

rookery job list [--limit LIMIT] [--host HOST] [--subject SUBJECT] [--running] [--before ID]
ArgumentWhat it is
--limit LIMITBy default 20.
--host HOSTOnly the jobs about this host.
--subject SUBJECTOnly the jobs of this subject, such as provisioner:NAME or installation.
--runningOnly the jobs that are still running.
--before IDOnly the jobs that started before this one, to see the next page.

rookery job show

One job's state.

rookery job show ID
ArgumentWhat it is
IDIts id.

rookery job logs

What a job wrote.

rookery job logs ID [-f, --follow]
ArgumentWhat it is
IDIts id.
-f, --followGo on as it writes more, until it ends.

rookery job wait

Wait for a job to end and exit with its result.

rookery job wait ID
ArgumentWhat it is
IDIts id.

rookery job stop

Stop a running job: its programs end, and its record says who stopped it.

rookery job stop ID
ArgumentWhat it is
IDIts id.

rookery key

The SSH keys rookery logs in to hosts with.

rookery key list

The keys of rookery's key ring, by their public halves.

rookery key ls is the same.

rookery key list

rookery key show

One key's public half, which a host's operator takes.

rookery key show [NAME]
ArgumentWhat it is
NAMEIts name. By default rookery.

rookery key create

Make a new ed25519 key.

rookery key create NAME
ArgumentWhat it is
NAMEIts name.

rookery key import

Add an OpenSSH private key without a passphrase from FILE (- for standard input).

rookery key import NAME FILE
ArgumentWhat it is
NAMEIts name.
FILEThe private key file, in OpenSSH format.

rookery key remove

Remove a key no host logs in with.

rookery key rm is the same.

rookery key remove NAME
ArgumentWhat it is
NAMEIts name.

rookery key rotate

Replace a key on every host that takes it.

rookery key rotate NAME [--detach]
ArgumentWhat it is
NAMEIts name.
--detachPrint the job's id and return; rookery job wait ID waits for it. Needs a rookery serve.

rookery key trust

Install a key on a host that does not take it yet, with a password used once.

rookery key trust HOST [--key NAME] [--password-stdin]
ArgumentWhat it is
HOSTA host's name.
--key NAMELog in once with this key of the ring, to install the one the host logs in with.
--password-stdinRead the password from standard input.

rookery secret

Secret values the server keeps and gives to hosts.

rookery secret list

The names of the secrets.

rookery secret ls is the same.

rookery secret list

rookery secret set

Set a secret's value: asked for, or read from a file or standard input.

rookery secret set NAME [--value-file FILE]
ArgumentWhat it is
NAMEIts name.
--value-file FILERead the value from FILE.

rookery secret rename

Give a secret another name. The profiles that hand it to hosts go on doing so.

rookery secret mv is the same.

rookery secret rename NAME NEW
ArgumentWhat it is
NAMEThe secret, by its name or its id.
NEWIts new name.

rookery secret remove

Remove a secret.

rookery secret rm is the same.

rookery secret remove NAME
ArgumentWhat it is
NAMEIts name.

rookery registry

Registries: Nexus servers, npm, file and Docker registries.

rookery registry list

The registries.

rookery registry ls is the same.

rookery registry list

rookery registry add

Add a registry, or change its address or user.

rookery registry add NAME TYPE URL [--user USER]
ArgumentWhat it is
NAMEIts name.
TYPEnexus, npm, raw or docker.
URLThe address.
--user USERThe user of its login; without one the login is a token.

rookery registry add-repo

Add a repository of a Nexus registry.

rookery registry add-repo NAME FORMAT REPOSITORY [--address ADDRESS]
ArgumentWhat it is
NAMEIts name.
FORMATnpm, raw or docker.
REPOSITORYThe repository's name on the registry.
--address ADDRESSIts own address, HOST[:PORT], for a Docker repository.

rookery registry login

Keep the password or token of a registry.

rookery registry login NAME [--password-stdin]
ArgumentWhat it is
NAMEIts name.
--password-stdinRead it from standard input.

rookery registry check

Whether a registry answers and takes its login.

rookery registry check [NAME]
ArgumentWhat it is
NAMEIts name.

rookery registry rename

Give a registry another name. Its login and the hosts that use it stay with it.

rookery registry mv is the same.

rookery registry rename NAME NEW
ArgumentWhat it is
NAMEThe registry, by its name or its id.
NEWIts new name.

rookery registry remove

Remove a registry with its login.

rookery registry rm is the same.

rookery registry remove NAME
ArgumentWhat it is
NAMEIts name.

rookery registry publish

Upload the release archive to a raw repository or file server, and use it as HOST's release address.

rookery registry publish DESTINATION [--host HOST] [--login REGISTRY]
ArgumentWhat it is
DESTINATIONREGISTRY or REGISTRY/REPOSITORY.
--host HOSTA host's name.
--login REGISTRYThe cloud seed carries this registry's login; the destination's without a name.

rookery registry push-image

Push rookery's container image.

rookery registry push-image DESTINATION [TAG]
ArgumentWhat it is
DESTINATIONREGISTRY or REGISTRY/REPOSITORY.
TAGBy default latest.

rookery plugin

Plugins and what they install.

rookery plugin list

The plugins and where they come from.

rookery plugin ls is the same.

rookery plugin list

rookery plugin show

What a plugin brings: its features with their actions, services and channels, and its provisioners.

rookery plugin show ID
ArgumentWhat it is
IDIts id.

rookery plugin add

Install a plugin with npm: a name, or the address of a tarball.

rookery plugin add SPEC
ArgumentWhat it is
SPECA plugin's npm name, or the address of its .tgz.

rookery plugin remove

Remove one of the server's own plugins.

rookery plugin rm is the same.

rookery plugin remove ID
ArgumentWhat it is
IDIts id.

rookery plugin update

Update one plugin or all to their registry's latest version.

rookery plugin update [ID] [--check]
ArgumentWhat it is
IDIts id.
--checkOnly say which have a newer version.

rookery config

The settings: the server's, and this rookery's own, such as the server it uses.

rookery config list

The settings, with what each means and where it is kept.

rookery config ls is the same.

rookery config list

rookery config get

One setting's value.

rookery config get KEY
ArgumentWhat it is
KEYThe setting or key.

rookery config set

Change a setting.

rookery config set KEY VALUE
ArgumentWhat it is
KEYThe setting or key.
VALUEThe value.

rookery config unset

Set a setting back to its default.

rookery config unset KEY
ArgumentWhat it is
KEYThe setting or key.

rookery port

Reach a port of a host, or an endpoint of a resource, from this machine.

rookery port forward

Listen on this machine and pass each connection to a port of a host, or to an endpoint of a resource.

TARGET is a host's name. A resource's id or name is taken when no host has that name, or always with --resource.

rookery port forward TARGET [LOCAL:]PORT|ENDPOINT… [--resource] [--address ADDRESS]
ArgumentWhat it is
TARGETA host's name, or a resource's id or name.
`[LOCAL:]PORTENDPOINT…`
--resourceTARGET is a resource, even where a host has the same name.
--address ADDRESSThe address to listen on. By default 127.0.0.1.

rookery inbox

Messages taken in from the hosts' channels.

rookery inbox list

The messages, oldest first.

rookery inbox ls is the same.

rookery inbox list [HOST] [--topic PREFIX] [--all] [--before SEQ]
ArgumentWhat it is
HOSTA host's name.
--topic PREFIXOnly topics that start with PREFIX.
--allDone ones as well.
--before SEQOnly those taken in before this one, by the number the list ends with.

rookery inbox done

Mark a message done, so the list leaves it out.

rookery inbox done HOST ID
ArgumentWhat it is
HOSTA host's name.
IDIts id.

rookery inbox reopen

Mark a done message as open again.

rookery inbox reopen HOST ID
ArgumentWhat it is
HOSTA host's name.
IDIts id.

rookery kv

The server's key-value store.

rookery kv list

The keys of a namespace with their values.

rookery kv ls is the same.

rookery kv list NAMESPACE
ArgumentWhat it is
NAMESPACEThe namespace.

rookery kv get

One key's value.

rookery kv get NAMESPACE KEY
ArgumentWhat it is
NAMESPACEThe namespace.
KEYThe setting or key.

rookery kv set

Write a key: JSON, or else text.

rookery kv set NAMESPACE KEY VALUE
ArgumentWhat it is
NAMESPACEThe namespace.
KEYThe setting or key.
VALUEThe value.

rookery kv remove

Remove a key.

rookery kv rm is the same.

rookery kv remove NAMESPACE KEY
ArgumentWhat it is
NAMESPACEThe namespace.
KEYThe setting or key.

rookery channel

A host's channel.

rookery channel listen

Messages on a host's channel as they come, one JSON object per line.

rookery channel listen HOST [--topic PREFIX] [--since ID]
ArgumentWhat it is
HOSTA host's name.
--topic PREFIXOnly topics that start with PREFIX.
--since IDFrom after this message on.

rookery service

Services that plugins run on a host.

rookery service call

Call a method of a service a plugin runs on the host.

rookery service call HOST SERVICE METHOD [BODY]
ArgumentWhat it is
HOSTA host's name.
SERVICEPLUGIN/NAME of the service.
METHODThe service's method.
BODYThe body, as JSON.

rookery server

The rookery server of this machine: running it, its setup key, its store and its API documents.

rookery server run

Serve the API over all hosts on a socket of this user, and over HTTP with --listen.

rookery server run [--listen ADDRESS:PORT] [--expose] [--simulate] [--seed FILE] [--delay SECONDS] [--data DIR] [--keep]
ArgumentWhat it is
--listen ADDRESS:PORTAlso listen over HTTP, behind a token.
--exposeAllow an address other than this machine's own.
--simulateRun a simulated server to test an application against: the real API on a scratch store, with hosts and provisioners that reach no machine.
--seed FILEA JSON file with the hosts, provisioners, secrets and token the simulated server starts with.
--delay SECONDSSeconds a simulated step takes, 2 unless given; 0 for none.
--data DIRKeep the simulated server's state in DIR, an empty one or one of an earlier simulation, instead of a scratch directory.
--keepLeave the scratch directory when the simulated server ends.

rookery server setup-key

Make a key, valid for a day, that lets the first user collect the server's token.

rookery server setup-key [--revoke]
ArgumentWhat it is
--revokeEnd the key that is open.

rookery server store

Where the server keeps its state, and sealing it.

rookery server store status

Where the store is, and whether it is sealed.

rookery server store status

rookery server store encrypt

Seal the store's values with a new key file.

rookery server store encrypt

rookery server store rekey

Seal them with another key.

rookery server store rekey

rookery server store decrypt

Write them plain again.

rookery server store decrypt

rookery server store copy

Copy the store into another SQLite file or PostgreSQL database, and switch to it.

rookery server store copy [TARGET] [--target-file FILE] [--into-existing]
ArgumentWhat it is
TARGETA file, a PostgreSQL URL, or - to read it from standard input.
--target-file FILERead the target from FILE.
--into-existingCopy into a database that holds a store already.

rookery server api

The server's API documents.

rookery server api openapi

The OpenAPI document.

rookery server api openapi

rookery server api asyncapi

The AsyncAPI document of the streams.

rookery server api asyncapi

rookery server api operations

The operations, with their routes and roles.

rookery server api operations

rookery server image

Build the server's image from this rookery with this machine's Docker engine.

rookery server image [--tag TAG]
ArgumentWhat it is
--tag TAGThe image's tag: rookery:VERSION, this rookery's version, unless another is given.

rookery server deploy

Run the rookery server on a machine with Docker, over SSH: from an image built there from this rookery, or from a release.

rookery server deploy [USER@]HOST [--container NAME] [--port PORT] [--release VERSION]
ArgumentWhat it is
[USER@]HOSTThe machine, as ssh reaches it with your own keys and settings.
--container NAMEThe server's container there. By default rookery.
--port PORTThe port the server listens on there, on 127.0.0.1. A new container gets 7777 without it.
--release VERSIONPull the published image of this version instead, as ghcr.io/aiviarium/rookery:VERSION.

rookery serve

Short for rookery server run.

rookery serve [--listen ADDRESS:PORT] [--expose] [--simulate] [--seed FILE] [--delay SECONDS] [--data DIR] [--keep]
ArgumentWhat it is
--listen ADDRESS:PORTAlso listen over HTTP, behind a token.
--exposeAllow an address other than this machine's own.
--simulateRun a simulated server to test an application against: the real API on a scratch store, with hosts and provisioners that reach no machine.
--seed FILEA JSON file with the hosts, provisioners, secrets and token the simulated server starts with.
--delay SECONDSSeconds a simulated step takes, 2 unless given; 0 for none.
--data DIRKeep the simulated server's state in DIR, an empty one or one of an earlier simulation, instead of a scratch directory.
--keepLeave the scratch directory when the simulated server ends.

rookery login

Use the rookery server at URL, with a setup key made there.

rookery login URL [--setup-key-stdin]
ArgumentWhat it is
URLhttps://HOST or http://HOST:PORT.
--setup-key-stdinRead the setup key from standard input.

rookery logout

Stop using the rookery server rookery login kept.

rookery logout

rookery update

Install the latest release in this program's place.

rookery update [--check] [--from URL]
ArgumentWhat it is
--checkOnly say whether there is a newer release.
--from URLWhere releases are, instead of rookery's own.

rookery version

The version of this rookery, and of the server it uses.

rookery version

rookery completion

The completions of a shell, to source from its start-up file.

rookery completion SHELL
ArgumentWhat it is
SHELLbash, zsh, fish, elvish or powershell. One of bash, elvish, fish, powershell, zsh.
Edit on GitHub

Last updated on

On this page

Flags of every commandExit statusesEnvironmentrookery lsrookery applyrookery execrookery sshrookery runrookery uirookery hostrookery host listrookery host showrookery host createrookery host addrookery host setrookery host editrookery host exportrookery host importrookery host applyrookery host seedrookery host isorookery host renamerookery host removerookery host duplicaterookery host adoptrookery host credentialsrookery host verifyrookery host startrookery host stoprookery host inventoryrookery rolloutrookery actionrookery action listrookery sessionrookery session listrookery session attachrookery session logsrookery session stoprookery provisionerrookery provisioner listrookery provisioner typesrookery provisioner addrookery provisioner showrookery provisioner setrookery provisioner renamerookery provisioner removerookery provisioner actionsrookery provisioner runrookery resourcerookery resource listrookery resource showrookery resource createrookery resource setrookery resource removerookery resource logsrookery resource execrookery resource actionsrookery resource runrookery jobrookery job listrookery job showrookery job logsrookery job waitrookery job stoprookery keyrookery key listrookery key showrookery key createrookery key importrookery key removerookery key rotaterookery key trustrookery secretrookery secret listrookery secret setrookery secret renamerookery secret removerookery registryrookery registry listrookery registry addrookery registry add-reporookery registry loginrookery registry checkrookery registry renamerookery registry removerookery registry publishrookery registry push-imagerookery pluginrookery plugin listrookery plugin showrookery plugin addrookery plugin removerookery plugin updaterookery configrookery config listrookery config getrookery config setrookery config unsetrookery portrookery port forwardrookery inboxrookery inbox listrookery inbox donerookery inbox reopenrookery kvrookery kv listrookery kv getrookery kv setrookery kv removerookery channelrookery channel listenrookery servicerookery service callrookery serverrookery server runrookery server setup-keyrookery server storerookery server store statusrookery server store encryptrookery server store rekeyrookery server store decryptrookery server store copyrookery server apirookery server api openapirookery server api asyncapirookery server api operationsrookery server imagerookery server deployrookery serverookery loginrookery logoutrookery updaterookery versionrookery completion