# Shako CLI reference

Every command of the `shako` CLI, with its arguments and examples, and plain SSH into your VMs. The same text is at https://shako.dev/cli and in `shako <command> --help`.

Install on macOS and Linux: `curl -fsSL https://shako.dev/install.sh | sh`. On Windows, in PowerShell: `irm https://shako.dev/install.ps1 | iex`. Setup for an AI agent: https://shako.dev/get-started.md.

## Get Started

You need a Shako account. shako login connects this computer to it and sets up plain SSH to your VMs.

### shako login

Log in this device: approve it in the workspace, then set up ssh to your VMs.

Usage: `shako login [flags]`

- `--no-browser`: Only print the link (open it on this computer).
- `--name <name>`: The name of this device's key (default: asked on the terminal, the host name is the default answer).

```sh
# Log in this computer: approve it in the workspace, which opens in the browser. Then plain ssh to your VMs works.
shako login

# Give this computer's key a name.
shako login --name work-laptop

# Only print the link, and open it in a browser on this computer.
shako login --no-browser
```

### shako whoami

Your tenants, your role in each, and the VM sizes.

Usage: `shako whoami`

```sh
# Your account name, the form of your SSH names and app URLs, and the sizes with their prices.
shako whoami

# Your account, then the key that this computer signs with.
shako whoami && shako config show
```

### shako update

Replace this CLI with the newest build. In a Shako VM (with sudo), also Shako's own tools in the VM.

Usage: `shako update`

```sh
# Replace this CLI with the newest build. If the download or the new file fails, the CLI does not change.
shako update

# Update, then check the version.
shako update && shako version
```

### shako version

The CLI's version.

Usage: `shako version`

```sh
# The version of the CLI on this computer.
shako version

# Only the version number, for a script.
shako version | cut -d' ' -f2
```

## VMs

Create, copy, resize and delete VMs. By default, a VM sleeps when it is quiet and wakes on the next SSH login or request.

### shako vm create

Create and boot a VM.

Usage: `shako vm create <name> [flags]`

- `<name>` (required): The new VM's name: a-z, 0-9 and single hyphens, starting with a letter, at most 31 characters. It is in the VM's SSH name and in the URLs of its public ports.
- `--size <size>`: The size: small 1cpu/2G/16G disk, mid 2cpu/4G/32G disk, large 4cpu/8G/64G disk, xl 4cpu/16G/128G disk (default small).
- `--cpus <cpus>`: Custom vCPUs: 1 or an even number. It replaces the vCPUs of the size.
- `--memory <memory>`: Custom memory, for example 3G or 2560M. The disk is 8 GB per GB of memory. It replaces the memory of the size.
- `--image <image>`: Image release, e.g. 2026.10.27.1 (default: the current release).
- `--sleep <sleep>`: When the VM sleeps. auto: when it is quiet; never: it stays on, and restarts after a reboot or a crash. With both, shako vm sleep and shako vm wake work at once (default auto).
- `--idle <idle>`: The quiet time before the VM sleeps, for example 15m or 2h (default 15m).
- `--no-wait`: Return before the guest's SSH is up.
- `--agent <agent>`: An AI agent or a coding agent to put in the VM: claude, codex, opencode, pi, kiro, openclaw, hermes. Give several with commas (--agent claude,codex) or with one --agent for each.
- `--desktop`: Browser use and computer use for the agents: a screen and a shared browser. Needs an agent and 4 GB of memory or more (size mid or bigger).
- `--isolated`: The key in the VM acts nowhere: no shako commands and no SSH to other VMs from the VM. SSH into the VM, the internet and its URLs still work.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Create a VM of the default size, Small.
shako vm create web1

# A VM with Claude Code and Codex, and a screen and a shared browser for them. These need size Mid or bigger.
shako vm create agents --size mid --agent claude,codex --desktop

# A custom size that never sleeps.
shako vm create db --cpus 2 --memory 3G --sleep never
```

### shako vm ls

List your VMs: the VMs of all your tenants.

Usage: `shako vm ls [flags]`

- `--tenant <tenant>`: Only the VMs of this tenant.

```sh
# List the VMs of all your tenants: state, size, disk, sleep policy, last activity and agents.
shako vm ls

# Only the VMs that are awake.
shako vm ls | grep awake

# Only the VMs of one tenant.
shako vm ls --tenant acme
```

### shako vm info

Show one VM.

Usage: `shako vm info <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Show one VM: size, SSH name, agents, sleep policy, snapshot, usage and its last events.
shako vm info web1

# Two VMs' details, one after the other.
shako vm info web1 && shako vm info api
```

### shako vm crons

List the crons in a VM (cron and the schedulers of its agents) and its next wake. The box asks an awake VM now. A sleeping VM does not wake: the list is the one of its last sleep.

Usage: `shako vm crons <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# List the crons in a VM: their source, schedule and next run, and when the box wakes the VM next.
shako vm crons assistant

# The crons of two VMs, one after the other.
shako vm crons assistant && shako vm crons web1
```

### shako vm sleep

Put a VM to sleep now.

Usage: `shako vm sleep <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Put a VM to sleep now. Its programs stay in memory, saved on disk.
shako vm sleep web1

# Put two VMs to sleep.
shako vm sleep web1 && shako vm sleep api
```

### shako vm wake

Wake a VM.

Usage: `shako vm wake <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Wake a VM. An SSH login or a request to a public port also wakes it.
shako vm wake web1

# Wake two VMs together, before a script runs.
shako vm wake web1 && shako vm wake api
```

### shako vm restart

Restart a VM: a clean shutdown, then a boot from its disk. Its running programs stop, and its files stay.

Usage: `shako vm restart <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Restart a VM. Its running programs stop, and its files stay.
shako vm restart web1

# Restart a VM, then log in to it again.
shako vm restart web1 && ssh web1.maya.shako.dev
```

### shako vm update

Update Shako's own tools in a VM (shako-session, shako-wake) and its shako CLI to the build of main, over ssh. The files in the VM and the running sessions stay. New sessions use the new tools.

Usage: `shako vm update <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Give a VM the newest Shako tools, for example the session status in the web workspace. Your files stay.
shako vm update web1

# Update two VMs.
shako vm update web1 && shako vm update api
```

### shako vm resize

Change size: the VM restarts, and its disk follows the new memory.

Usage: `shako vm resize <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--size <size>`: The new size: small 1cpu/2G/16G disk, mid 2cpu/4G/32G disk, large 4cpu/8G/64G disk, xl 4cpu/16G/128G disk.
- `--cpus <cpus>`: Custom vCPUs: 1 or an even number. Only the vCPUs change.
- `--memory <memory>`: Custom memory, for example 3G or 2560M. The disk is 8 GB per GB of memory. Only the memory and the disk change.
- `--restart`: Allow restarting a running or sleeping VM.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Make a VM bigger. The VM restarts.
shako vm resize web1 --size large --restart

# Give a VM 6 GB of memory. Its disk grows to 60 GB.
shako vm resize web1 --memory 6G --restart

# Give a VM 1 vCPU.
shako vm resize web1 --cpus 1 --restart
```

### shako vm set

Change sleep policy, if crons and chat messages wake the VM, if the VM is isolated, and its backups.

Usage: `shako vm set <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--sleep <sleep>`: When the VM sleeps. auto: when it is quiet; never: it stays on, and restarts after a reboot or a crash. With both, shako vm sleep and shako vm wake work at once.
- `--idle <idle>`: The quiet time before the VM sleeps, for example 15m or 2h.
- `--wake-on-cron <wake_on_cron>`: On (the default): after each sleep, the VM wakes 2 minutes before its next cron job. off: it does not. On for a sleeping VM starts at its next sleep.
- `--wake-on-chat <wake_on_chat>`: On or off: wake the VM when a chat message comes (default on).
- `--isolated <isolated>`: On: the key in the VM acts nowhere: no shako commands and no SSH to other VMs from the VM. SSH into the VM, the internet and its URLs still work. off: the VM acts as you again. The change is at once, with no reboot.
- `--backup <backup>`: On (the default): each night, Shako backs up the VM if its disk changed. off: no new backups, and the old backups go 7 days after they were taken.
- `--after-delete <after_delete>`: What happens to the VM's backups when you delete the VM. keep-7d (the default): they stay 7 days, then Shako erases them. erase: Shako erases them within a few minutes. After an erase, the storage keeps the deleted data 7 more days, then deletes it.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Sleep after 30 quiet minutes.
shako vm set web1 --sleep auto --idle 30m

# A VM that never sleeps, for example for a bot or a server.
shako vm set bot --sleep never

# Keep a VM asleep through its cron jobs.
shako vm set web1 --wake-on-cron off
```

### shako vm rename

Give a VM a new name. Its SSH name and the URLs of its shared ports change too, and the old ones stop working.

Usage: `shako vm rename <vm> <new_name> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `<new_name>` (required): The new name, by the rule of a new VM's name.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Rename a VM. Its old SSH name and the old URLs of its shared ports stop working.
shako vm rename web1 site

# Rename a VM, then show the new URLs of its shared ports.
shako vm rename web1 site && shako port ls site
```

### shako vm cp

Copy a VM: a new VM whose disk starts as a copy-on-write copy of the source VM's disk. It gets the size, image and agents of the source VM, and boots with new SSH host keys.

Usage: `shako vm cp <source> <name> [flags]`

- `<source>` (required): The VM to copy, from shako vm ls.
- `<name>` (required): The new VM's name: a-z, 0-9 and single hyphens, starting with a letter, at most 31 characters. It is in the VM's SSH name and in the URLs of its public ports.
- `--sleep <sleep>`: When the VM sleeps. auto: when it is quiet; never: it stays on, and restarts after a reboot or a crash. With both, shako vm sleep and shako vm wake work at once (default: the sleep policy of the source VM).
- `--idle <idle>`: The quiet time before the VM sleeps, for example 15m or 2h (default: the quiet time of the source VM).
- `--no-wait`: Return before the guest's SSH is up.
- `--isolated`: The key in the VM acts nowhere: no shako commands and no SSH to other VMs from the VM. SSH into the VM, the internet and its URLs still work. The source must be isolated: its copy is isolated also without this flag.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Copy a VM, for example to try a risky change on the copy.
shako vm cp web1 web1-test

# A copy that sleeps after 5 quiet minutes.
shako vm cp web1 web1-test --idle 5m

# Return at once, before the copy's SSH is up.
shako vm cp web1 web2 --no-wait
```

### shako vm logs

The VM's console output.

Usage: `shako vm logs <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `-n, --lines <lines>`: How many of the last lines to show (default 100, at most 10000).
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# The last 100 lines of the VM's console.
shako vm logs web1

# The last 500 lines.
shako vm logs web1 -n 500

# Find errors in the console output.
shako vm logs web1 -n 1000 | grep -i error
```

### shako vm usage

Awake and asleep hours, RAM GB-hours and cost per VM.

Usage: `shako vm usage [flags]`

- `--range <range>`: The time: this week (from Monday), this month, or all (default).
- `--vm <vm>`: Only the VMs with this name, deleted ones too.
- `--days`: Also the cost of each day, on this computer's clock.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# The hours awake and asleep of each VM with usage, and its RAM GB-hours (memory times those hours), and its cost in US dollars. One row holds all the deleted VMs with one name. The most awake GB-hours come first, then the most asleep. Then the totals, with the total cost.
shako vm usage

# The cost of the VMs named web1 this month, deleted ones too, and of each day.
shako vm usage --range month --vm web1 --days
```

### shako vm rm

Delete a VM and its disk.

Usage: `shako vm rm <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--yes`: Confirm the delete. Without --yes, nothing is deleted.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Delete a VM, its disk and its public ports. You cannot undo this.
shako vm rm web1-test --yes

# Without --yes, nothing is deleted: the CLI only tells what the delete does.
shako vm rm web1-test

# Delete a VM, and its backups within a few minutes, not after 7 days.
shako vm set web1-test --after-delete erase && shako vm rm web1-test --yes
```

## SSH Into a VM

Each VM is a plain SSH host. After shako login, ssh, scp, sftp and port forwarding work as on any server.

### ssh

Log in to a VM, or run one command in it. A sleeping VM wakes first. In the VM you are the user shako, and sudo gives root with no password.

Usage: `ssh <vm>.<tenant>.shako.dev [command]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `<tenant>` (required): Your account's name, from shako whoami.
- `[command]`: A command to run in the VM, in place of a shell.

```sh
# Log in to a VM.
ssh web1.maya.shako.dev

# Run one command.
ssh web1.maya.shako.dev df -h

# Install a package as root.
ssh web1.maya.shako.dev sudo apt-get install -y ripgrep
```

### scp, sftp, rsync

Copy files between this computer and a VM. A path in a VM is <vm>.<tenant>.shako.dev:<path>.

Usage: `scp <from> <to>`

- `<from>` (required): The file or folder to copy: a path on this computer or in a VM.
- `<to>` (required): Where the copy goes: a path on this computer or in a VM.
- `-r`: Copy a folder and all that is in it.

```sh
# Copy a file to the home folder of the VM.
scp ./app.tar.gz web1.maya.shako.dev:~/

# Copy a folder from the VM to this computer.
scp -r web1.maya.shako.dev:~/site ./site

# Copy only the changed files with rsync. The VM needs rsync too: install it once.
ssh web1.maya.shako.dev sudo apt-get install -y rsync && rsync -avz ./site/ web1.maya.shako.dev:~/site/
```

### ssh -L

Open a private port of a VM on this computer, through SSH. Use it for a database or an app that only you use: the port stays private.

Usage: `ssh -N -L <local-port>:localhost:<vm-port> <vm>.<tenant>.shako.dev`

- `<local-port>` (required): The port on this computer.
- `<vm-port>` (required): The port in the VM.
- `-N`: Only forward the port, and run no command.

```sh
# Open the VM's Postgres at localhost:5432 on this computer.
ssh -N -L 5432:localhost:5432 web1.maya.shako.dev

# See a private dev server at http://localhost:3000.
ssh -N -L 3000:localhost:3000 web1.maya.shako.dev

# Forward two ports with one connection.
ssh -N -L 5432:localhost:5432 -L 6379:localhost:6379 web1.maya.shako.dev
```

## Backups

A backup is a copy of a VM's disk, kept outside its box. A restore puts the disk back to a backup, and the VM restarts. With backups on, Shako backs up the current disk first, so you can undo a restore. shako vm set --backup and --after-delete are the privacy settings of a VM.

### shako backup ls

List a VM's backups, newest first: the ID, the time on this computer's clock, the kind (nightly, manual or pre-restore) and the data that it added to the store. Then the backup or restore that runs now, or the last one if it failed.

Usage: `shako backup ls <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# List a VM's backups: the ID, the time, the kind and the data that each one added. Then the backup or restore that runs now.
shako backup ls web1

# Only the nightly backups.
shako backup ls web1 | grep nightly
```

### shako backup create

Back up a VM now. The VM keeps running. This backup replaces the last manual backup. The command waits until the backup is done.

Usage: `shako backup create <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--no-wait`: Return at once. The backup goes on, and shako backup ls shows it.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Back up a VM now, for example before a risky change. The VM keeps running, and the CLI waits until the backup is done.
shako backup create web1

# Start the backup and return at once. Then see how it goes.
shako backup create web1 --no-wait && shako backup ls web1
```

### shako backup restore

Put a VM's disk back to one of its backups. The VM restarts, and the files that changed after the backup go back. Shako backs up the current disk first (kind pre-restore), so you can undo. With backups off for the VM (shako vm set --backup off), it does not, and you cannot undo. Without --yes, the CLI asks first.

Usage: `shako backup restore <vm> <id> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `<id>` (required): The backup's ID, from shako backup ls.
- `--yes`: Do not ask first.
- `--no-wait`: Return at once. The restore goes on, and shako backup ls shows it.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Put a VM's disk back to a backup, with its ID from shako backup ls. The CLI asks first, and the VM restarts.
shako backup restore web1 9f3c1a2e

# Restore with no question, for example in a script.
shako backup restore web1 9f3c1a2e --yes

# Undo a restore: restore the pre-restore backup that it made of the disk of before.
shako backup restore web1 7d01b4c9
```

### shako backup erase

Delete every backup of a VM now. You cannot undo this. The VM stays, and with backups on, the next night backs it up again. The storage keeps the deleted data 7 more days, then deletes it. Without --yes, the CLI asks first.

Usage: `shako backup erase <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--yes`: Do not ask first.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Erase every backup of a VM now. The CLI asks first, and the VM stays. The storage deletes the last copies within 7 days.
shako backup erase web1

# Stop the backups of a VM, then erase the old ones now with no question.
shako vm set web1 --backup off && shako backup erase web1 --yes
```

## Ports and Public URLs

A public port gets its own HTTPS address, https://<vm>-<port>--<tenant>.shakoapp.dev. Anyone with the address can open it.

### shako port ls

List a VM's ports, or only one port.

Usage: `shako port ls <vm> [port] [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `[port]`: Show only this port, and check if a program listens on it.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# The shared ports of a VM, and the common ports that listen.
shako port ls web1

# One port: is it shared, and does a program listen on it?
shako port ls web1 8000
```

### shako port share

Share a port at a URL, on your private network or for the internet.

Usage: `shako port share <vm> <port> <access> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `<port>` (required): The port in the VM, 1 to 65535. A program must listen on it on 0.0.0.0, not 127.0.0.1.
- `<access>` (required): Public: anyone on the internet can open https://<vm>-<port>--<tenant>.<apps domain>. private: only your devices can open https://<vm>-<port>--<tenant>.net.<apps domain>.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Share port 3000 at https://web1-3000--maya.shakoapp.dev. Anyone can open it.
shako port share web1 3000 public

# Share an admin page at https://auction-8080--maya.net.shakoapp.dev. Only your devices can open it.
shako port share auction 8080 private
```

### shako port unshare

Stop sharing a port. Its URL stops working.

Usage: `shako port unshare <vm> <port> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `<port>` (required): A shared port of the VM.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Stop sharing port 3000. Its URL stops working.
shako port unshare web1 3000

# Stop sharing a database port, and reach it only from this computer through SSH.
shako port unshare web1 5432 && ssh -N -L 5432:localhost:5432 web1.maya.shako.dev
```

## Your Private Network

A private port opens only on your devices, with no password, at https://<vm>-<port>--<tenant>.net.shakoapp.dev. Add this computer once. Its tunnel stays on, and it carries only the traffic to Shako.

### shako device add

Add this computer to your private network. It installs WireGuard if it is missing, and starts a tunnel that stays on, also after a reboot. It uses sudo.

Usage: `shako device add [name] [flags]`

- `[name]`: The device's name (default: this computer's host name).
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Add this computer to your private network, with its host name as the device's name.
shako device add

# Give the device a name, then share a port that only your devices can open.
shako device add work-laptop && shako port share auction 8080 private
```

### shako device ls

List your devices.

Usage: `shako device ls [flags]`

- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# List your devices: name, the day you added each one, and the last time its tunnel was up.
shako device ls

# Find one device by its name.
shako device ls | grep laptop
```

### shako device rm

Remove a device. Its tunnel stops at once. On this computer, the tunnel's files go too.

Usage: `shako device rm <name> [flags]`

- `<name>` (required): The device's name, from shako device ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Remove a device. Its tunnel stops at once.
shako device rm old-laptop

# Find the device's name first.
shako device ls && shako device rm old-laptop
```

## Agent Sessions and the Screen

The terminal sessions of a VM, the same ones as in the web workspace. A session runs an agent or a shell, and it keeps running when you leave it.

### shako session new

Start a session with a name in a folder and attach to it. To leave the session running, close the terminal or type ~. at the start of a line (ssh's escape).

Usage: `shako session new <vm> <session> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `<session>` (required): The new session's name, for example api or fix-login. No other session of the VM may have it.
- `--agent <agent>`: The agent to run: claude, codex, opencode, pi, kiro, openclaw, hermes. The VM must have it. Default: a shell.
- `--dir <dir>`: The folder in the VM to start in, an absolute path (default /home/shako). It must exist, unless --mkdir.
- `--mkdir`: Make the folder first (and the folders above it).
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Start Claude Code in a new session api, in a new folder.
shako session new web1 api --agent claude --dir /home/shako/api --mkdir

# A shell in the home folder.
shako session new web1 shell

# Codex in a folder that exists.
shako session new web1 fix-login --agent codex --dir /home/shako/app
```

### shako session ls

List a VM's sessions: the name, the agent, and the status of the program in it (working, blocked, done or idle). A shell, or a session from before shako vm update, has no status.

Usage: `shako session ls <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# List the sessions of a VM and the status of each agent. The web workspace shows the same sessions.
shako session ls web1

# List the sessions, then attach to one.
shako session ls web1 && shako session attach web1 api
```

### shako session attach

Attach to a session. To leave the session running, close the terminal or type ~. at the start of a line (ssh's escape).

Usage: `shako session attach <vm> <session> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `<session>` (required): The session's name, from shako session ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Attach to the session api. To leave it running, close the terminal or type ~. at the start of a line.
shako session attach web1 api

# Attach to a session that you started in the web workspace.
shako session attach web1 dashboard
```

### shako session rename

Give a session a new name.

Usage: `shako session rename <vm> <session> <new_name> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `<session>` (required): The session's name, from shako session ls.
- `<new_name>` (required): The new name. No other session of the VM may have it.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Rename the session api to api-v2.
shako session rename web1 api api-v2

# Give a shell session a name that tells what it does.
shako session rename web1 shell build
```

### shako session rm

Delete a session: end it and the program in it.

Usage: `shako session rm <vm> <session> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `<session>` (required): The session's name, from shako session ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# End the session api and the program in it.
shako session rm web1 api

# End two sessions.
shako session rm web1 api && shako session rm web1 shell
```

### shako screen open

Forward the VM's screen to a port on this computer for a VNC viewer, until Ctrl-C. Only a VM with agents and size mid or bigger has a screen.

Usage: `shako screen open <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--take`: Take over, for example for a login, a 2FA code or a CAPTCHA: the agents' browser and screen tools wait until this command stops.
- `--port <port>`: The port on 127.0.0.1 (default 5901).
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Watch the agents' screen: open vnc://127.0.0.1:5901 in a VNC viewer. On a Mac, Screen Sharing opens it.
shako screen open agents

# Take over, for example for a login or a 2FA code. The agents' browser and screen tools wait until you stop the command.
shako screen open agents --take

# Use another port on this computer.
shako screen open agents --port 5902
```

### shako build open

Open the VM's build page (workspace.shako.dev/build) in this computer's browser. Only a VM with an agent has T3 Code.

Usage: `shako build open <vm> [flags]`

- `<vm>` (required): The VM's name, from shako vm ls.
- `--no-browser`: Only print the link.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Open T3 Code in the VM agents, in this computer's browser. Code with its agents there.
shako build open agents

# Only print the link, for example to open it on another computer.
shako build open agents --no-browser
```

## Agent Memory

Notes of up to 2000 tokens that Shako adds to each LLM request from your VMs, for every agent. While memory is on, each request from your VMs to a model provider goes through Shako. Your login goes to the provider unchanged, and Shako does not keep it. While memory is off, the requests go straight to the provider.

### shako memory show

Show the notes, and if they are on.

Usage: `shako memory show [flags]`

- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Show the notes, and if they are on.
shako memory show

# Read long notes one screen at a time.
shako memory show | less
```

### shako memory edit

Change the notes in $EDITOR, and save them when the editor closes.

Usage: `shako memory edit [flags]`

- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Change the notes in your editor. They are saved when the editor closes.
shako memory edit

# Use nano.
EDITOR=nano shako memory edit

# Use VS Code.
VISUAL="code --wait" shako memory edit
```

### shako memory set

Replace the notes with the text of a file.

Usage: `shako memory set --file <file> [flags]`

- `--file <file>` (required): The file, or - for the standard input.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Replace the notes with the text of a file.
shako memory set --file notes.md

# Replace the notes with one line.
echo "Always answer in bullet points." | shako memory set --file -
```

### shako memory on

Send each LLM request from your VMs, also from your own programs, through Shako, which adds the notes.

Usage: `shako memory on [flags]`

- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Add the notes to each LLM request from your VMs.
shako memory on

# Write the notes, then turn them on.
shako memory set --file notes.md && shako memory on
```

### shako memory off

Stop adding the notes: the LLM requests from your VMs go straight to the providers.

Usage: `shako memory off [flags]`

- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Stop adding the notes. The text stays.
shako memory off

# Turn the notes off for one test, then on again.
shako memory off && shako memory on
```

## Secrets

A secret, such as a GitHub token, that your VMs use but cannot read. Each VM gets a placeholder, and Shako puts the value in place of it in the requests to the hosts of the secret. The value never goes into a VM.

### shako secret set

Add a secret or replace it. The value comes from the standard input, or else the CLI asks for it and does not show what you type. Each VM gets the variable NAME=shako-secret-NAME, and Shako puts the value in place of shako-secret-NAME in each request to the hosts. The value never goes into a VM.

Usage: `shako secret set <secret> --host <host> [flags]`

- `<secret>` (required): The secret's name, also the name of the variable in your VMs, for example GH_TOKEN: A-Z, 0-9 and _, not first a digit, at most 64 characters.
- `--host <host>` (required): A host that gets the value: github.com or api.github.com. Give --host for each host.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Give your VMs the GitHub login of this computer. Then git clone, git push and gh work with your private repositories in each VM, and no VM has the token.
gh auth token | shako secret set GH_TOKEN --host github.com --host api.github.com

# Type the value: the CLI asks for it and does not show it.
shako secret set GH_TOKEN --host github.com --host api.github.com

# Take the value from a file. With github.com only, git works, but gh does not: gh uses api.github.com.
shako secret set GH_TOKEN --host github.com < token.txt
```

### shako secret ls

List your secrets: the name, the hosts, the last 4 characters of a long value, and when it changed. No command shows a value.

Usage: `shako secret ls [flags]`

- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# List your secrets: the name, the hosts, the last 4 characters of a long value, and when it changed.
shako secret ls

# Check that a secret is there.
shako secret ls | grep GH_TOKEN
```

### shako secret rm

Remove a secret. Shako stops putting its value in the requests of your VMs.

Usage: `shako secret rm <secret> [flags]`

- `<secret>` (required): The secret's name, from shako secret ls.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Remove a secret. Shako stops putting its value in the requests of your VMs.
shako secret rm GH_TOKEN

# Find the secret's name first.
shako secret ls && shako secret rm GH_TOKEN
```

## Credit

Your VMs use prepaid credit. Awake, a VM pays for its memory and its disk. Asleep, it pays for its disk only.

### shako credit show

Show the balance, the credit, and the cost of your VMs since billing started.

Usage: `shako credit show [flags]`

- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Show what is left of your credit, and what your VMs used.
shako credit show

# Show only the balance.
shako credit show | head -1
```

### shako credit add

Add credit: pay on a Stripe page in the browser. The credit goes up when Stripe tells Shako that it is paid.

Usage: `shako credit add <AMOUNT> [flags]`

- `<AMOUNT>` (required): The US dollars to add: 5, 10, 25, 50.
- `--no-browser`: Only print the link of the payment page.
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Add $10 of credit: pay on the Stripe page that opens in the browser.
shako credit add 10

# Only print the link of the payment page, and open it on another computer.
shako credit add 25 --no-browser
```

### shako credit invoice

Save the PDF invoice of a month: each VM's usage and cost.

Usage: `shako credit invoice [MONTH] [flags]`

- `[MONTH]`: The month, YYYY-MM (default: this month, on this computer's clock).
- `-o, --output <output>`: The file to write (default: shako-invoice-<name>-<month>.pdf in this folder).
- `--tenant <tenant>`: The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

```sh
# Save the PDF invoice of this month so far, in this folder.
shako credit invoice

# Save the invoice of October 2026 as oct.pdf.
shako credit invoice 2026-10 -o oct.pdf
```

## Tenants

A tenant has its own VMs, credit and invoices. You can own many tenants and share one with other accounts: each one accepts with the link of an email. With more than one tenant, a command that acts in a tenant needs --tenant.

### shako tenant ls

List your tenants, your role in each (owner or member), and the default: the tenant of a command with no --tenant.

Usage: `shako tenant ls`

```sh
# List your tenants and your role in each: owner or member.
shako tenant ls

# Only the tenants that you own.
shako tenant ls | grep owner
```

### shako tenant create

Create a tenant that you own. It has its own VMs, credit and invoices. Only the first tenant that you create gets the free credit, one time.

Usage: `shako tenant create <name>`

- `<name>` (required): The new tenant's name: a-z, 0-9 and single hyphens, at most 20 characters. It is in the SSH names and the URLs of its VMs.

```sh
# Make a second tenant, with its own VMs, credit and invoices. It starts at $0.
shako tenant create acme

# Make a tenant, then a VM in it.
shako tenant create acme && shako vm create web1 --tenant acme
```

### shako tenant rm

Delete a tenant that you own. It must have no VMs, and no other members or invites. Its credit, secrets, devices and agent memory go.

Usage: `shako tenant rm <name> [flags]`

- `<name>` (required): The tenant's name, from shako tenant ls.
- `--yes`: Confirm the delete. Without --yes, nothing is deleted.

```sh
# Delete a tenant that you own. It must have no VMs, and no other members or invites. You cannot undo this.
shako tenant rm acme --yes

# Delete the last VM of a tenant, then the tenant.
shako vm rm web1 --yes --tenant acme && shako tenant rm acme --yes
```

### shako tenant share

Invite another account to a tenant: its VMs, ports, devices and agent memory. The account gets an email, and it is a member when it opens the link. It must have logged in to Shako once. Only the owner shares.

Usage: `shako tenant share <name> <email>`

- `<name>` (required): The tenant's name, from shako tenant ls.
- `<email>` (required): The email of the account.

```sh
# Invite a colleague to a tenant. They must have logged in to Shako once, and they accept with the link of the email.
shako tenant share acme bob@example.com

# Invite an account, then show the accounts of the tenant: it is invited until it accepts.
shako tenant share acme bob@example.com && shako tenant members acme
```

### shako tenant unshare

Stop sharing a tenant with an account, or cancel its invite. Its VMs stay in the tenant, and their keys and its devices stop working there. Only the owner unshares. A member can leave: give your own email.

Usage: `shako tenant unshare <name> <email>`

- `<name>` (required): The tenant's name, from shako tenant ls.
- `<email>` (required): The email of the account.

```sh
# Stop sharing a tenant with an account, or cancel its invite. Its VMs stay in the tenant.
shako tenant unshare acme bob@example.com

# Leave a tenant that another account shares with you.
shako tenant unshare acme you@example.com
```

### shako tenant members

List the accounts of a tenant and their roles.

Usage: `shako tenant members <name>`

- `<name>` (required): The tenant's name, from shako tenant ls.

```sh
# Show the accounts of a tenant and their roles.
shako tenant members acme

# Only the members, not the owner.
shako tenant members acme | grep member
```

## SSH Keys

The keys that log in to your VMs and sign the requests of the CLI. shako login adds the key of this computer.

### shako key ls

List your SSH keys, then the keys of the VMs of the other members of your tenants.

Usage: `shako key ls`

```sh
# List the SSH keys of your account: name, type, fingerprint and scope.
shako key ls

# Find one key by its name.
shako key ls | grep laptop
```

### shako key add

Add a key with a name.

Usage: `shako key add <key> --name <name>`

- `<key>` (required): The public key or its .pub file.
- `--name <name>` (required): The key's name, for example the computer's name.

```sh
# Add the key of a computer with no browser, from its .pub file.
shako key add ./build-server.pub --name build-server

# Add a key from its text.
shako key add "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... ci@runner" --name ci
```

### shako key rm

Remove the key with this name. The key of a VM stays in shako key ls, off: it acts nowhere.

Usage: `shako key rm <name>`

- `<name>` (required): The key's name, from shako key ls.

```sh
# Remove a key. It cannot log in after that.
shako key rm old-laptop

# Find the key's name first.
shako key ls && shako key rm ci
```

## This Computer

The settings of the CLI on this computer.

### shako config show

Show the API and the key that this device uses.

Usage: `shako config show`

```sh
# Show the API and the SSH key that this computer uses.
shako config show

# Change the key, then check it.
shako config set --key ~/.ssh/shako_ed25519 && shako config show
```

### shako config set

Set the API, the key or both.

Usage: `shako config set [flags]`

- `--api <api>`: The address of the Shako API (default https://api.shako.dev).
- `--key <key>`: The SSH key that signs your requests, e.g. ~/.ssh/id_ed25519.

```sh
# Sign requests with another SSH key.
shako config set --key ~/.ssh/shako_ed25519

# Go back to the default API.
shako config set --api https://api.shako.dev
```
