Freestyle CLI

Use the freestyle CLI for interactive administration, debugging, and automation scripts.

Install

The CLI ships in the freestyle npm package. Run it without installing:

npx freestyle@latest --help

Or install it globally:

pnpm add -g freestyle@latest

bun add -g freestyle@latest

npm install -g freestyle@latest

yarn global add freestyle@latest

freestyle --version

Authenticate

For local use, log in through the browser. The CLI stores a refresh token and team preference in ~/.freestyle/config.json. Logging in does not mint a permanent API key by itself; create one with freestyle tokens create when you need it.

freestyle login
freestyle login --no-browser
freestyle whoami
freestyle team list
freestyle team current
freestyle team use <name-or-id>
freestyle logout

Use an API key for CI and non-interactive automation. A logged-in CLI can mint one:

freestyle tokens create "ci deploys"
export FREESTYLE_API_KEY="your-api-key"
freestyle vm list

The key is shown once. List and revoke keys with freestyle tokens list and freestyle tokens revoke <key-id>. These are account API keys, not the per-end-user tokens under freestyle identity token.

For scripts, add --output json to freestyle tokens create and read the key from the token field.

The CLI also reads FREESTYLE_API_KEY from a .env file in the current directory. Credential precedence is --api-key, the environment, .env, then the stored login. An API key already belongs to one team, so team selection applies only to browser login.

For a stored login, select a team with --team, FREESTYLE_TEAM, or freestyle team use, in that order.

Commands

Run --help at any level to see the available actions and flags:

freestyle vm --help
freestyle snapshot create --help
freestyle tunnels attach --help
freestyle domain verify --help
freestyle identity permission --help

Common Workflows

# Create a named VM, then run a command in it. At a terminal, `vm create`
# opens a shell in the new VM; `--no-ssh` prints it instead.
freestyle vm create --slug development --no-ssh
freestyle vm exec development -- uname -a

# Set a fresh VM up with a script, then capture it as a snapshot.
freestyle snapshot create --script ./setup.sh --slug configured-worker

# Open an interactive shell or copy files over SSH.
freestyle vm ssh development
freestyle vm scp ./app.tar development:/root/app.tar

# Create a VPC with a chosen IPv4 range and attach a VM to it.
freestyle vpc create --slug private --cidr 10.40.0.0/24
freestyle vm create --slug worker --vpc private --ipv4 10.40.0.10

# Route a free style.dev name to a VM with a TLS rule — no verification needed.
freestyle tls create --domain my-app.style.dev --from public --to vm=development,port=3000

# Or verify a domain of your own first, then route it.
freestyle domain verify create example.com
freestyle domain verify complete example.com
freestyle tls create --domain app.example.com --from public --to vm=development,port=3000

# Mint an API key for CI, and redeem a credit code. Both need a login.
freestyle tokens create "ci deploys"
freestyle billing redeem FS-XXXXXXXXXX

See VM CLI and Domains CLI for focused examples.

Output And Global Options

The default pretty output is designed for people. Use the global output option for scripts:

freestyle --output json vm list | jq '.vms[].id'

Global options can appear before a command:

freestyle --team production vm list
freestyle --api-key "$KEY" vm get worker
freestyle --proxy http://localhost:8787 vm list

vm exec streams guest stdout and stderr directly and exits with the guest process’s status code. Other successful mutations print the updated record; delete operations print a one-line confirmation.