ws-cli clip
Reach the browser clipboard from the terminal over the workspace IPC socket.
ws-cli clip paste
Read the browser clipboard over the workspace IPC socket and write it to stdout — redirect it to a file or pipe it onward. Pairs with the pbcopy/xclip/xsel shims for terminal clipboard access.
ws-cli clip paste
ws-cli editor
Query and control the running VS Code / code-server window over the workspace IPC socket — list open tabs, read diagnostics and the current selection, or open a file. Blocked over SSH, where there is no browser editor to reach.
| Flag | Description | Default |
|---|---|---|
--raw | Output the raw JSON response without styling | false |
ws-cli editor diagnostics
Pull language-server diagnostics (errors, warnings) from the editor over the IPC socket, across the whole workspace or a single file with --uri. Styled table by default, --raw for the JSON.
ws-cli editor diagnostics [flags]
| Flag | Description | Default |
|---|---|---|
--uri | Filter to a single file (URI or absolute path) |
ws-cli editor list
List the editor's open tabs over the IPC socket, with each tab's path, language, and active or dirty state.
ws-cli editor list
ws-cli editor open
Open a file in the running editor window over the workspace IPC socket — a tab in the current window by default, a separate one with --new-window, jumping to a range with --selection. Fails fast over SSH, where there is no browser editor to open into.
ws-cli editor open <file> [flags]
| Flag | Description | Default |
|---|---|---|
--new-window | Open in a new window | false |
--preview | Open as a preview tab (reuse-window only) | false |
--reuse-window | Open in the current window as a tab (default) | false |
--selection | Select a range: LINE:COL[-LINE:COL] (1-based) |
ws-cli editor selection
Report the active editor's current selection — file, range, and selected text — over the IPC socket. Empty when nothing is selected.
ws-cli editor selection
ws-cli feature
Install and inspect optional workspace features — Ansible playbooks that add tools on top of the base image. Ships a curated set; --root points at your own under ~/.ws/features.d.
| Flag | Description | Default |
|---|---|---|
--root | Root directory of additional features |
ws-cli feature info
Show a feature's description and the variables it accepts, so you know what --opt values install will take.
ws-cli feature info <name>
ws-cli feature install
Run a feature's playbook to install it. Pass variables with --opt KEY=VAL, and skip parts you do not want with --skip-extensions, --skip-completion, or --skip-repository.
ws-cli feature install [flags]
| Flag | Description | Default |
|---|---|---|
--opt | Optional variables to use during installation | [] |
--skip-completion | Skip configuring shell completion | false |
--skip-extensions | Skip installing VSCode extensions | false |
--skip-repository | Skip enabling the vendor APT repository | false |
ws-cli feature listalias: ls
List the features you can install, marking where each comes from — the shipped set, a workspace override, or your own ~/.ws/features.d.
ws-cli feature list
ws-cli feature new
Print a starter feature playbook to stdout. Redirect it into ~/.ws/features.d/.yaml, then extend it and install with "ws-cli feature install ": ws-cli feature new redis > ~/.ws/features.d/redis.yaml
ws-cli feature new [name]
ws-cli feature store
List the artifacts published to the feature store (WS_FEATURES_STORE_URL) — the offline mirror features install from when the network is locked down.
ws-cli feature store
ws-cli info
Report facts about the running workspace — version, effective environment, installed extensions, live resource metrics, and uptime.
ws-cli info env
Print every WS_* variable in effect, sorted — the resolved environment the workspace booted with.
ws-cli info env
ws-cli info extensions
List the installed VS Code extensions with their versions.
ws-cli info extensions
ws-cli info metrics
Show live resource usage — CPU, memory, disk, and file descriptors, plus GPU with --gpu.
ws-cli info metrics [flags]
| Flag | Description | Default |
|---|---|---|
--gpu | Include GPU metrics | false |
ws-cli info uptime
Show when the workspace session started and how long it has been running.
ws-cli info uptime
ws-cli info version
Print the workspace version. --all expands to the full table — workspace, ws-cli, and VS Code.
ws-cli info version [flags]
| Flag | Description | Default |
|---|---|---|
--all | Show all version information | false |
ws-cli log
Emit styled, level-tagged log lines — the same formatting the startup scripts use. --pipe runs each line of piped input through the logger.
| Flag | Description | Default |
|---|---|---|
--pipe, -p | Loop through piped output | false |
ws-cli log debug
Emit a log line at debug level in the workspace style — the same formatting the startup scripts use. --indent nests it under a preceding line, --stamp prefixes a timestamp.
ws-cli log debug message [flags]
| Flag | Description | Default |
|---|---|---|
--indent, -i | Desired prefixed indentation | 0 |
--stamp, -s | Prefix message with current timestamp | false |
ws-cli log error
Emit a log line at error level in the workspace style — the same formatting the startup scripts use. --indent nests it under a preceding line, --stamp prefixes a timestamp.
ws-cli log error message [flags]
| Flag | Description | Default |
|---|---|---|
--indent, -i | Desired prefixed indentation | 0 |
--stamp, -s | Prefix message with current timestamp | false |
ws-cli log info
Emit a log line at info level in the workspace style — the same formatting the startup scripts use. --indent nests it under a preceding line, --stamp prefixes a timestamp.
ws-cli log info message [flags]
| Flag | Description | Default |
|---|---|---|
--indent, -i | Desired prefixed indentation | 0 |
--stamp, -s | Prefix message with current timestamp | false |
ws-cli log stamp
Print just the current timestamp in the workspace log style — handy for marking phases in a startup log.
ws-cli log stamp
ws-cli log warn
Emit a log line at warn level in the workspace style — the same formatting the startup scripts use. --indent nests it under a preceding line, --stamp prefixes a timestamp.
ws-cli log warn message [flags]
| Flag | Description | Default |
|---|---|---|
--indent, -i | Desired prefixed indentation | 0 |
--stamp, -s | Prefix message with current timestamp | false |
ws-cli logs
Read a workspace daemon's log — the main log by default, or --target metrics|docker|auth_proxy|cloudflared. Filter by --level, limit with --tail, or stream live with --follow.
ws-cli logs [flags]
| Flag | Description | Default |
|---|---|---|
--follow, -f | Follow log output in real-time | false |
--level, -l | Filter by log level (debug|info|warn|error) | |
--tail, -t | Number of lines to show from the end (0 for all) | 0 |
--target | Log target to read (main|metrics|docker|auth_proxy|cloudflared) | main |
ws-cli secrets
Encrypt and decrypt values under a master key, and generate the keys themselves. Encrypted values are what the seed engine's secrets: map stores and decrypts at boot.
| Flag | Description | Default |
|---|---|---|
--force | Overwrite existing files | false |
--master | Master key or path to key file | |
--mode | File permissions (e.g., 0o600, 384), only when --output is used | |
--output | Write output to file instead of stdout | |
--raw | Output without styling | false |
ws-cli secrets decrypt
Decrypt a value produced by encrypt, under the master key. Reads from the argument or stdin (-); writes the plaintext to stdout, or a file with --output.
ws-cli secrets decrypt <encrypted|->
ws-cli secrets encrypt
Encrypt a value under the master key. Reads the plaintext from the argument or stdin (-); writes the ciphertext to stdout, or a file with --output.
ws-cli secrets encrypt <plaintext|->
ws-cli secrets generate
Generate the credentials the workspace needs — a master key for secrets, or a login password hash for the server.
ws-cli secrets generate login
Prompt for a password and print its hash for the workspace server login (WS_AUTH_PASSWORD_HASHED). Store the hash, never the password.
ws-cli secrets generate login
ws-cli secrets generate master
Generate a random master key, printed base64-encoded — the key encrypt, decrypt, and the seed engine use. --length sets the byte size (default 32).
ws-cli secrets generate master [flags]
| Flag | Description | Default |
|---|---|---|
--length | Key length in bytes | 32 |
ws-cli seed
Copy files and apply small edits from a seed source onto the filesystem at boot. Bare files mirror verbatim; a .seed.yaml manifest overlays behavior — copy, merge, append — and decrypts secrets under the master key. Point --source at a mounted volume to seed a container from durable storage.
| Flag | Description | Default |
|---|---|---|
--source | Seed source directory |
ws-cli seed apply
Apply the seed source to the filesystem — mirror bare files and run the .seed.yaml operations. Writes only where the destination is missing unless --force; pass destinations to limit the run to those paths.
ws-cli seed apply [dest...] [flags]
| Flag | Description | Default |
|---|---|---|
--force | Overwrite existing destinations | false |
--master | Master key or path to key file |
ws-cli seed ls
List what apply would write — each destination with its operation and whether it carries a secret or a template — without touching the filesystem.
ws-cli seed ls
ws-cli seed rotate
Re-encrypt every managed secret from the old master key (--master) to a new one (--new-master), in place. All-or-nothing: it verifies every secret decrypts before writing anything.
ws-cli seed rotate [flags]
| Flag | Description | Default |
|---|---|---|
--master | Current master key or path to key file | |
--new-master | New master key or path to key file |
ws-cli serve
Run a small HTTP server for local assets — fonts or the current directory — on --port (default 38080).
| Flag | Description | Default |
|---|---|---|
--bind | Bind address | 0.0.0.0 |
--port, -p | Port to serve assets on | 38080 |
ws-cli serve current
Serve the current directory over HTTP as a static site — a quick way to preview built files.
ws-cli serve current [flags]
ws-cli serve current
Serve the current directory over HTTP as a static site — a quick way to preview built files.
ws-cli serve current [flags]
ws-cli serve font
Serve the installed fonts over HTTP so a browser can fetch them for local install.
ws-cli serve font [flags]
ws-cli serve font
Serve the installed fonts over HTTP so a browser can fetch them for local install.
ws-cli serve font [flags]
ws-cli serve metrics
ws-cli serve metrics [flags]
| Flag | Description | Default |
|---|---|---|
--collectors | Comma-separated list of collectors to enable (e.g., workspace,container.cpu,gpu) | [*] |
--port, -p | Port to serve metrics on | 9100 |
ws-cli show
Resolve and print facts about this workspace instance — settings, IP addresses, and paths. --raw drops the styling for use in scripts.
| Flag | Description | Default |
|---|---|---|
--raw | Output raw value without styling | false |
ws-cli show env
Resolve a setting by its dotted key (server.port) and print it with its source and description. --value emits just the value for scripts, --as bool|int|list validates the shape, --check tests whether it is set so a startup script can guard on it.
ws-cli show env <KEY> [flags]
| Flag | Description | Default |
|---|---|---|
--as | Validate and emit as one of: bool, int, list (mutex with --value) | |
--check | Check whether the variable (or its --deprecated alias) is set | false |
--delimiter | Override delimiter for --as=list (defaults to YAML delimiter or space) | |
--deprecated | Deprecated alias paired with --check | |
--or-skip | Exit 1 (not error) on the natural absence of the chosen projection | false |
--validate | Anchored regex each --as=list token must full-match; rejects fail-closed | |
--value | Emit the raw resolved value as a single line | false |
ws-cli show ip
Print the workspace's IP addresses — the internal container address or the node it runs on.
ws-cli show ip internal
Print the workspace container's internal IP address.
ws-cli show ip internal
ws-cli show ip node
Print the IP address of the node hosting the workspace.
ws-cli show ip node
ws-cli show path
Print well-known workspace paths — the home root or the VS Code settings file.
ws-cli show path home
Print the workspace home (server root) path.
ws-cli show path home
ws-cli show path vscode-settings
Print the path to the VS Code settings file — the user file by default, or the folder's with --workspace.
ws-cli show path vscode-settings [flags]
| Flag | Description | Default |
|---|---|---|
--workspace | Get the workspace settings | false |
ws-cli template
Copy shared configuration files (linters, formatters) from their global locations into a project, and inspect what they hold.
ws-cli template apply
Copy a template into the project — a shared config like ruff or markdownlint — to --path (the current directory by default). --force overwrites an existing file.
ws-cli template apply <template> [flags]
| Flag | Description | Default |
|---|---|---|
--force, -f | Overwrite existing files | false |
--path | Target directory path | . |
ws-cli template listalias: ls
List the templates you can apply, with their source paths and whether one is already applied here.
ws-cli template list
ws-cli template show
Display the contents of a configuration template. Available templates: ansible, markdownlint, ruff, yamllint
ws-cli template show <template> [flags]
| Flag | Description | Default |
|---|---|---|
--local | Show the local version of the template (if applied) | false |