@paperhand/cli

Command-line interface for Paperhand — provision ephemeral VMs from your terminal.

Install

npm install -g @paperhand/cli

Installs two equivalent commands: paperhand and the short alias ph (ph vm create … ≡ paperhand vm create …).

Requires Node.js 18 or newer (the CLI uses the built-in global fetch).

Getting an API key

1. Open the Paperhand dashboard.
2. Go to Workspace settings.
3. Open the API keys tab.
4. Click Generate key and copy it.

Then save it so the CLI can use it:

paperhand login --key ph_xxx
# or, to be prompted interactively:
paperhand login

The key is written to ~/.paperhand/config.json (owner-readable only).

API key resolution

The CLI looks for a key in this order (first match wins):

1. --key / -k flag
2. PAPERHAND_API_KEY environment variable
3. ~/.paperhand/config.json

Commands

Create a VM:

paperhand vm create --template node-22 --vcpu 4 --memory 8GB
# ✓ vm_7f3c ready

Run a command inside a VM (everything after -- is the command):

paperhand exec vm_7f3c -- npm test

Tear a VM down:

paperhand vm rm vm_7f3c
# ✓ vm_7f3c torn down

Pause a running VM:

paperhand vm pause vm_7f3c

List available templates:

paperhand templates list

Create a shelf:

paperhand shelves create my-shelf
# ✓ my-shelf (shelf_7f3c) created

Create a restricted shelf shared with specific users:

paperhand shelves create my-shelf --privacy restricted --user usr_1 --user usr_2
# or comma-separated:
paperhand shelves create my-shelf --privacy restricted --user usr_1,usr_2

Fetch a shelf by its id or slug:

paperhand shelves get my-shelf
# ✓ my-shelf (shelf_7f3c)
#   name:    My Shelf
#   privacy: private

Change a shelf's privacy (owner only), by id or slug:

paperhand shelves update-privacy my-shelf --privacy public
# ✓ my-shelf privacy set to public

# Make it restricted and share with specific users:
paperhand shelves update-privacy my-shelf --privacy restricted --user usr_1,usr_2

vm create options

| Flag | Default | Description | | ------------ | ------------- | --------------------------------------------- | | --template | — | Base template (accepted; not yet sent to API) | | --vcpu | 1 | Number of vCPUs | | --memory | 1GB | Memory size | | --storage | 4GB | Disk size | | --type | linux/amd64 | Platform / architecture | | --region | — | Preferred region (see valid values below) |

Valid --region values (mirrors the API's vmRegions): us-east, us-west, apac, ew-east, eu-central, hong-kong, africa-south, mainland-china.

shelves create options

| Flag | Default | Description | | ----------- | --------- | ------------------------------------------------------------------------------------- | | --privacy | private | Visibility: private, public, or restricted | | --user | — | Grant a user access (repeatable or comma-separated; only meaningful for restricted) |

shelves update-privacy options

| Flag | Default | Description | | ----------- | ------- | ------------------------------------------------------------------------------------- | | --privacy | — | Required. New visibility: private, public, or restricted | | --user | — | Grant a user access (repeatable or comma-separated; only meaningful for restricted) |

Global options

| Flag | Description | | ----------------- | ------------------------------------------- | | -k, --key | API key (overrides env var and config file) | | -h, --help | Show help | | -v, --version | Show the CLI version |

Environment variables

| Variable | Description | | -------------------- | --------------------------------------------------------------- | | PAPERHAND_API_KEY | Workspace API key | | PAPERHAND_BASE_URL | Override the API base URL (default: https://api.paperhand.io) |

License

MIT