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#

bash
easyenv ws list
easyenv ws list --status active --search review

# JSON output for scripts
easyenv ws list --output json

Create#

you@laptop: ~/work
# From a template, started and waited for
you@laptop:~/work$ easyenv workspace create --template python-dev-single --name review-pr-1284 --ttl 8h --wait
Created 9c0e7d21-... "review-pr-1284" - waiting for machines to start...
workspace: active machines: active
Workspace "review-pr-1284" is active.
# From a single recipe, without --wait
you@laptop:~/work$ easyenv workspace create --base ubuntu_24_04 --name scratch --ttl 2h
Created 4b7f30aa-... "scratch" (status: not_started)
you@laptop:~/work$ easyenv ws start 4b7f30aa-...
# From a YAML spec
you@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.

  • --wait starts the workspace, waits until every machine is active and prints the SSH details. Without it the workspace is created not_started and you start it with easyenv ws start <uuid>.
  • --ttl takes minutes, hours or days: 30m, 2h, 1d. Seconds are not accepted.
  • --dry-run resolves everything and prints the request body without sending it.

Inspect#

bash
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#

bash
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 2h

Delete#

bash
# With confirmation
easyenv ws delete <workspace-uuid>

# Skip the prompt (use carefully in scripts)
easyenv ws delete <workspace-uuid> --force

SSH 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:

bash
# 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 -a

See 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:

bash
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
Manage workspaces from the CLI | Docs | EasyEnv