CLI

The Puter CLI lets you manage your Puter resources straight from the terminal: deploy static websites, ship serverless workers, and inspect the apps registered to your account, all without leaving your shell.

Installation

Install the CLI globally with npm (requires Node 18+):

npm install -g @heyputer/cli

Then log in once and your token is stored for later commands:

puter login

This opens your browser to authenticate with Puter. Once you're logged in, you're ready to deploy.

Authentication

puter login runs an interactive browser flow and saves your token for future commands. If you don't have browser access (for example, on a remote server), pipe a token in via stdin instead:

echo "$TOKEN" | puter login --with-token

For automation and CI, set the PUTER_AUTH_TOKEN environment variable and the CLI skips login entirely, reading the token from the environment on every command.

puter whoami     # show the current account
puter logout     # clear the stored token

Sites

Deploy a static directory to a <subdomain>.puter.site address, then list, inspect, or remove your sites.

puter site deploy ./dist my-app

Run puter site deploy with no arguments and the CLI prompts you for the directory and subdomain interactively, suggesting an available name. Deploys are versioned: each deploy uploads into its own folder, so previous versions are preserved.

puter site deploy [dir] [subdomain]   # deploy a directory
puter site list                       # list your sites
puter site get <subdomain>            # show one site's details
puter site delete <subdomain>         # remove a site

Workers

Deploy a single JavaScript file as a serverless Worker, served at <name>.puter.work. Deploying with a name that already exists replaces that worker's code in place.

puter worker deploy ./api.js my-api

As with sites, running puter worker deploy with no arguments prompts you for the file and name.

puter worker deploy [file] [name]   # deploy or replace a worker
puter worker list                   # list your workers
puter worker get <name>             # show one worker's details
puter worker delete <name>          # delete a worker

Apps

Browse the apps registered to your account. These commands are read-only.

puter app list           # list your apps
puter app get <name>     # show one app's details

CLI reference

Global options

The CLI detects whether it's running interactively. In a terminal it prompts for any missing values; in a non-interactive context (CI, piped output, or with CI set) it never prompts, so required arguments must be passed explicitly.

puter login

Log in to Puter and store the token for later commands.

puter logout

Clear the stored auth token. Takes no arguments.

puter whoami

Show the account associated with the current token. Takes no arguments.

puter site deploy

Deploy a static directory to <subdomain>.puter.site.

In non-interactive mode both arguments are required. Subdomains may use lowercase letters, numbers, and hyphens (not at the ends).

puter site list

List the subdomains you own, with their URLs. Takes no arguments.

puter site get

Show details for one site.

puter site delete

Remove a subdomain.

puter worker deploy

Deploy a JavaScript file as a serverless worker at <name>.puter.work, or replace an existing one.

In non-interactive mode both arguments are required. Names may use letters, numbers, and hyphens (not at the ends).

puter worker list

List your workers, with their URLs. Takes no arguments.

puter worker get

Show details for one worker.

puter worker delete

Delete a worker and its backing file.

puter app list

List the apps registered to your account. Takes no arguments.

puter app get

Show details for one app.

Environment variables