Manage workspaces from the CLI
Spin workspaces up and down without leaving your terminal. Useful for scripted demos, CI integration tests, and quick sanity checks.
ws is short for workspace. Commands that act on one workspace take its UUID.
List workspaces#
easyenv ws list
easyenv ws list --status active --search review
# JSON output for scripts
easyenv ws list --output jsonCreate#
# From a template, started and waited foryou@laptop:~/work$ easyenv workspace create --template python-dev-single --name review-pr-1284 --ttl 8h --waitCreated 9c0e7d21-... "review-pr-1284" - waiting for machines to start...workspace: active machines: activeWorkspace "review-pr-1284" is active.# From a single recipe, without --waityou@laptop:~/work$ easyenv workspace create --base ubuntu_24_04 --name scratch --ttl 2hCreated 4b7f30aa-... "scratch" (status: not_started)you@laptop:~/work$ easyenv ws start 4b7f30aa-...# From a YAML specyou@laptop:~/work$ easyenv workspace create -f workspace.yml --wait
Pass exactly one of --template, --base (one machine from one recipe) or -f. Templates and recipes are looked up by UUID first, then by name; list them with easyenv template list and easyenv recipe list.
--waitstarts the workspace, waits until every machine is active and prints the SSH details. Without it the workspace is creatednot_startedand you start it witheasyenv ws start <uuid>.--ttltakes minutes, hours or days:30m,2h,1d. Seconds are not accepted.--dry-runresolves everything and prints the request body without sending it.
Inspect#
easyenv ws get <workspace-uuid>
easyenv ws get <workspace-uuid> --output json
# Stream workspace, machine and stack status until Ctrl-C
easyenv ws watch <workspace-uuid>get lists each machine with its status and the commands that reach it.
Stop and start#
easyenv ws stop <workspace-uuid>
easyenv ws start <workspace-uuid>
easyenv ws restart <workspace-uuid>
# Give it more time before the TTL runs out
easyenv ws extend <workspace-uuid> --duration 2hDelete#
# With confirmation
easyenv ws delete <workspace-uuid>
# Skip the prompt (use carefully in scripts)
easyenv ws delete <workspace-uuid> --forceSSH into a machine#
Machines are reached through the EasyEnv connection broker: the box dials out, so there is no VPN, no DNS and no public port. SSH works per machine:
# Find the machine UUIDs
easyenv machine list -w <workspace-uuid>
# Interactive shell
easyenv machine ssh <machine-uuid>
# One command, with the remote exit code passed through
easyenv machine exec <machine-uuid> -- uname -aSee Manage machines from the CLI for port forwarding, file copy, and plain ssh through a ProxyCommand.
Project workspaces#
Commit a .easyenv/workspace.yml to a repo and the here commands find its workspace from any directory inside it:
easyenv here up --wait 10m # create or reuse the workspace
easyenv here sync # rsync the project onto the machine
easyenv here run --cmd "make test" # sync, then run a command there
easyenv here expose # forward the ports listed in workspace.yml
easyenv here ssh # shell on the first machine
easyenv here down --force # stop and delete it