CLI reference
Generated from rooz 0.168.1.
rooz
Usage: rooz [OPTIONS] <COMMAND>
Commands:
new Creates a new workspace (container + volumes)
enter Opens an interactive shell to a workspace's container
exec Runs one command in a workspace container and exits with its exit code
code Attaches VsCode to a workspace. (requires VsCode installed and 'code' in $PATH)
start Starts a workspace
stop Stops a workspace
restart Restarts a workspace's work container
remove Removes a workspace
update Updates a workspace created from a config file
move Renames a workspace, or with --to moves it to another host: copies its volumes, rebuilds it there and removes the old one (the source is kept with --to)
list Lists workspaces
cache Manages the shared cache volumes
doctor Checks the engine connection, rooz's setup and the engine's headroom
status Shows a workspace's containers, volumes and config origin
logs Shows the logs of a workspace container
config Config subcommands
tmp Enters an ephemeral workspace
remote Connects to remote hosts: forwards their engine sockets and published ports. Stays in the foreground
system System subcommands
help Print this message or the help of the given subcommand(s)
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
-V, --version
Print version
rooz new
Creates a new workspace (container + volumes)
Usage: rooz new [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
-g, --git-ssh-url <GIT_SSH_URL>
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-i, --image <IMAGE>
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
--home-from-image <HOME_FROM_IMAGE>
--pull-image
-u, --user <USER>
--uid <UID>
--caches <CACHES>
Enables defining global shared caches
-p, --privileged <PRIVILEGED>
[possible values: true, false]
--allow-secrets <ALLOW_SECRETS>
Consents to expanding the 'secrets' of the --config file into this workspace
[possible values: true, false]
--start <START>
Starts the workspace immediately
[default: true]
[possible values: true, false]
--config-path <CONFIG_PATH>
Configures the new workspace from a config file given by the path.
--dry-run
Prints what would be created, without creating anything
-h, --help
Print help
rooz enter
Opens an interactive shell to a workspace's container
Usage: rooz enter [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-s, --shell <SHELL>
-r, --root
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-w, --work-dir <WORK_DIR>
-c, --container <CONTAINER>
--chown
Chowns the container's volume mounts to the user the container runs as
-h, --help
Print help
rooz exec
Runs one command in a workspace container and exits with its exit code
Usage: rooz exec [OPTIONS] <NAME> -- <CMD>...
Arguments:
<NAME>
<CMD>...
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-r, --root
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-w, --work-dir <WORK_DIR>
-c, --container <CONTAINER>
-h, --help
Print help
rooz code
Attaches VsCode to a workspace. (requires VsCode installed and 'code' in $PATH)
Usage: rooz code [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz start
Starts a workspace
Usage: rooz start [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz stop
Stops a workspace
Usage: rooz stop [OPTIONS] [NAME]
Arguments:
[NAME]
Options:
-a, --all
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz restart
Restarts a workspace's work container
Usage: rooz restart [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
--all-containers <ALL_CONTAINERS>
[default: false]
[possible values: true, false]
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz remove
Removes a workspace
Usage: rooz remove [OPTIONS] [NAME]
Arguments:
[NAME]
Options:
-f, --force
Kill running containers
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-a, --all
Remove all workspaces
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz update
Updates a workspace created from a config file
Usage: rooz update [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-t, --tweak
If set allows to tweak the existing config and apply the edited version.
--purge
If set it removes the workspace volumes. WARNING: potential data loss ahead
--no-pull
If set it skips pulling new images
--dry-run
Prints what the update would remove and create, without changing anything
--allow-secrets <ALLOW_SECRETS>
Consents to expanding the 'secrets' of the workspace config into the updated workspace
[possible values: true, false]
-h, --help
Print help
rooz move
Renames a workspace, or with --to moves it to another host: copies its volumes, rebuilds it there and removes the old one (the source is kept with --to)
Usage: rooz move [OPTIONS] <NAME> [NEW_NAME]
Arguments:
<NAME>
[NEW_NAME]
The new name; with --to it defaults to the current one
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
--to <TO>
Moves the workspace to this host (see 'rooz remote'; both hosts must be connected). The workspace is left stopped on the source
--remove-source
Removes the source workspace after a successful move
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
--dry-run
Prints what would be copied and rebuilt, without changing anything
--allow-secrets <ALLOW_SECRETS>
Consents to expanding the 'secrets' of the workspace config into the moved workspace
[possible values: true, false]
-h, --help
Print help
rooz list
Lists workspaces
Usage: rooz list [OPTIONS]
Options:
--all-hosts
Lists workspaces on all configured hosts that 'rooz remote' is connected to
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
--json
Prints JSON instead of a table
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz cache
Manages the shared cache volumes
Usage: rooz cache [OPTIONS] <COMMAND>
Commands:
ls Lists caches with size and the workspaces mounting them
rm Removes caches by name or path (e.g. '~/.cargo'); refuses mounted ones
prune Removes all caches that no workspace mounts
help Print this message or the help of the given subcommand(s)
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz cache ls
Lists caches with size and the workspaces mounting them
Usage: rooz cache ls [OPTIONS]
Options:
--all-scopes
Includes other operators' caches (see ROOZ_CACHE_SCOPE)
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
--json
Prints JSON instead of a table
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz cache rm
Removes caches by name or path (e.g. '~/.cargo'); refuses mounted ones
Usage: rooz cache rm [OPTIONS] <NAMES>...
Arguments:
<NAMES>...
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz cache prune
Removes all caches that no workspace mounts
Usage: rooz cache prune [OPTIONS]
Options:
--dry-run
Prints what would be removed, without removing
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz doctor
Checks the engine connection, rooz's setup and the engine's headroom
Usage: rooz doctor [OPTIONS]
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz status
Shows a workspace's containers, volumes and config origin
Usage: rooz status [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
--json
Prints JSON instead of text
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz logs
Shows the logs of a workspace container
Usage: rooz logs [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
-c, --container <CONTAINER>
A sidecar name; the work container by default
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-f, --follow
Keeps streaming new output
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
--tail <TAIL>
Number of lines from the end, e.g. 100
-h, --help
Print help
rooz config
Config subcommands
Usage: rooz config [OPTIONS] <COMMAND>
Commands:
template Outputs a workspace configuration template
edit Edits a local configuration file
show Shows a workspace's configuration
schema Outputs the JSON Schema of the config file format, for editor completion and validation
help Print this message or the help of the given subcommand(s)
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz config template
Outputs a workspace configuration template
Usage: rooz config template [OPTIONS]
Options:
--detect [<DIR>]
Looks for Cargo.toml, *.csproj/*.sln, package.json, go.mod and pyproject.toml/requirements.txt in DIR (default: the current directory) and fills in the image and caches
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz config edit
Edits a local configuration file
Usage: rooz config edit [OPTIONS] <CONFIG_PATH>
Arguments:
<CONFIG_PATH>
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz config show
Shows a workspace's configuration
Usage: rooz config show [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-p, --part <PART>
[default: body]
[possible values: origin, body, runtime]
--resolved
Shows the merged settings (defaults, bases, config) and the layer each came from
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz config schema
Outputs the JSON Schema of the config file format, for editor completion and validation
Usage: rooz config schema [OPTIONS]
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz tmp
Enters an ephemeral workspace
Usage: rooz tmp [OPTIONS]
Options:
-g, --git-ssh-url <GIT_SSH_URL>
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-i, --image <IMAGE>
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
--home-from-image <HOME_FROM_IMAGE>
--pull-image
-u, --user <USER>
--uid <UID>
--caches <CACHES>
Enables defining global shared caches
-p, --privileged <PRIVILEGED>
[possible values: true, false]
--allow-secrets <ALLOW_SECRETS>
Consents to expanding the 'secrets' of the --config file into this workspace
[possible values: true, false]
--start <START>
Starts the workspace immediately
[default: true]
[possible values: true, false]
-r, --root
-s, --shell <SHELL>
[env: ROOZ_SHELL]
[default: bash]
-h, --help
Print help
rooz remote
Connects to remote hosts: forwards their engine sockets and published ports. Stays in the foreground
Usage: rooz remote [OPTIONS] [NAMES]...
rooz remote <COMMAND>
Commands:
add Adds or updates a remote host
rm Removes a remote host
ls Lists configured remote hosts
help Print this message or the help of the given subcommand(s)
Arguments:
[NAMES]...
Hosts to connect to. Default: all configured
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz remote add
Adds or updates a remote host
Usage: rooz remote add [OPTIONS] <NAME> <SSH_URL>
Arguments:
<NAME>
Host name, used with -H/--host
<SSH_URL>
Host's SSH url, e.g. ssh://user@host
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
--socket <SOCKET>
Path to the container engine socket on the host. Default: $DOCKER_HOST as seen by a non-interactive ssh command
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz remote rm
Removes a remote host
Usage: rooz remote rm [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz remote ls
Lists configured remote hosts
Usage: rooz remote ls [OPTIONS]
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz system
System subcommands
Usage: rooz system [OPTIONS] <COMMAND>
Commands:
prune Prunes all rooz resources
init Initializes rooz system
completion Outputs shell completion scripts
configure Opens the system config in EDITOR
help Print this message or the help of the given subcommand(s)
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz system prune
Prunes all rooz resources
Usage: rooz system prune [OPTIONS]
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz system init
Initializes rooz system
Usage: rooz system init [OPTIONS]
Options:
-f, --force
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
--age-identity <AGE_IDENTITY>
Initializes rooz with the provided age identity rather than generating a new one
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
--rotate-ssh-key
Generates a new ssh key pair, replacing the current one. Every workspace on this engine gets the new key, and the old one must be de-registered wherever you added it
-h, --help
Print help
rooz system completion
Outputs shell completion scripts
Usage: rooz system completion [OPTIONS] <SHELL>
Arguments:
<SHELL>
[possible values: bash, elvish, fish, powershell, zsh]
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help
rooz system configure
Opens the system config in EDITOR
Usage: rooz system configure [OPTIONS]
Options:
-H, --host <HOST>
Runs against a host from 'rooz remote ls' instead of DOCKER_HOST
[env: ROOZ_HOST]
-v, --verbose
Prints debug logging (RUST_LOG still applies when this is not set)
-h, --help
Print help