CLI Guide | STATICX

Public npm CLI

Run STATICX from a terminal with the same token-protected API contract.

The public staticx CLI is a friendly wrapper around /api/v1. Install it, log in once with a bearer token, then create sites, deploy builds, and inspect logs without leaving your shell.

npm install -g staticx

staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
staticx guide
staticx whoami

Where to generate tokens

Create the token from the surface that matches the job.

Global token

Open Settings → API tokens when one operator or internal tool needs account-wide access.

Best for: listings, dashboards, broad internal automation.

Site token

Open Project Settings → Agent deploy when the CLI only needs one site.

Best for: CI runs, deploy bots, one-off release jobs.

Workspace token

Open Workspace → Agent deploy when one runner must stay inside one workspace.

Best for: multi-site client workspaces, team release tools.

Ready-made command sets

Use the smallest scope that still lets the CLI finish.

Global

Best when one operator needs account-wide visibility before creating or listing sites.

npm install -g staticx

staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
staticx guide
staticx whoami
staticx workspaces
staticx create --workspace-id WORKSPACE_ID --name "Marketing Site"

Workspace

Best when the runner must stay inside one workspace but still create or inspect multiple sites there.

npm install -g staticx

staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
staticx guide
staticx whoami
staticx sites --workspace-id WORKSPACE_ID
staticx create --workspace-id WORKSPACE_ID --name "Client Site"

Site

Best for the smallest release scope when the CLI only needs deploy and log access to one site.

npm install -g staticx

staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
staticx guide
staticx whoami
staticx deploy --site-id SITE_ID --dir dist
staticx logs --site-id SITE_ID

Expected command flow

How the CLI should behave.

Install the package. npm install -g staticx.
Log in with a token. staticx login --base-url ... --token ... stores the base URL, verifies the token, and prints the active scope plus next commands.
Open the terminal guide. staticx guide explains the supported commands without leaving the shell.
Verify access. staticx whoami calls GET /user and returns the current token metadata.
Create or deploy. Use the scope-specific commands shown above.
Inspect logs after changes. Use staticx logs --site-id ... when a deploy or upload needs verification.

API contract

Keep the CLI on the same route set as every other integration.

Command	Routes	Purpose
`staticx guide`	Local helper	Explain login, browsing, creation, deploy, logs, token scopes, and required build files.
`staticx whoami`	`GET /user`	Verify the token and return scope metadata.
`staticx workspaces`	`GET /workspaces`	List visible workspaces for a Global token.
`staticx sites --workspace-id ...`	`GET /projects?workspace_id=...`	List sites inside one workspace.
`staticx create --workspace-id ...`	`POST /projects`	Create a new site, optionally inside a workspace.
`staticx deploy --site-id ... --dir dist`	`POST /projects/{project}/files`, `POST /projects/{project}/deployments`	Upload a build with `index.html` and `404.html`, then publish it.
`staticx logs --site-id ...`	`GET /projects/{project}/logs`	Read project activity after deploys and uploads.

Strong defaults

Keep the CLI safe by default.

Prefer a Site token for deploy jobs that only touch one site.
Use a Workspace token only when the same runner truly needs multiple sites inside one workspace.
Reserve Global tokens for internal operator workflows, never routine release jobs.
Keep token expiry short whenever the CLI job is temporary.
Do not print tokens in logs, commits, screenshots, or support messages.