About the PW CLI

The Parallel Works command-line interface (PW CLI) offers a streamlined way to interact with your compute and storage resources from a terminal.

Installation

By default, the PW CLI is pre-installed on user workspaces, cloud clusters, and existing clusters. You can open a terminal on the ACTIVATE platform and immediately use any PW CLI command.

For existing clusters, the PW CLI is installed in a folder named pw inside your home directory.

Install Script (Recommended)

The easiest way to install the PW CLI is with the install script, which automatically detects your operating system and architecture. This works on Linux and macOS:

curl -fsSL https://activate.parallel.works/cli/install.sh | bash

By default, the CLI is installed to ~/.local/bin. You can specify a custom install location with the --to flag:

curl -fsSL https://activate.parallel.works/cli/install.sh | bash -s -- --to /usr/local/bin

Manual Installation

If you prefer to download the binary manually, or are on Windows, follow the instructions below for your operating system and device's chip type.

mkdir -p ~/bin
wget "https://activate.parallel.works/cli/pw-linux-amd64" -O ~/bin/pw

Authentication

User workspaces and existing clusters are pre-authenticated. You can access the PW CLI and immediately interact with your compute and storage resources.

On cloud clusters and your own computer, sign in with pw auth. For CI and scheduled services, use an API key. See Authentication for CLI and scripts to choose a method, handle long-running scripts, and isolate credentials.

Sign in

To sign in to a platform for the first time, pass its host:

pw auth cloud.parallel.works

The CLI opens your browser, where you sign in as usual, including single sign-on and 2-step verification. There is no API key to copy.

On a cloud cluster, or any computer without a browser, use --device:

pw auth --device cloud.parallel.works

The CLI prints an address and a short code. Open the address on any device, enter the code, and check that the page names the computer you are signing in from before you approve it. The CLI also falls back to a code when it can't open a browser, such as over SSH.

The sign-in is saved as a context named user@host in ~/.config/pw/credentials and becomes the current context. Use --context-name to choose a different name. To sign in again to the current context's platform, run pw auth with no host. pw auth login is the same command.

The CLI renews its short-lived access tokens while you use it. A sign-in still has idle and maximum lifetime limits, so you will eventually need to sign in again. Where your operating system has a credential store, such as the macOS Keychain, the long-lived part of the sign-in is kept there instead of in the credentials file. Run pw auth logout to sign this computer out.

See pw auth for all options.

Signed-in devices

Each computer you sign in from is listed under Settings > Connected apps, where you can sign it out without affecting your other devices. Organization admins can see and sign out a member's CLI devices from that member's sessions.

Organization and platform admins can turn off sign-in with a code using the Disable Device Code Sign-in policy. Then pw auth --device, and any sign-in that falls back to a code, is refused. Sign in through a browser on the same computer, or use an API key.

Scripts

On a computer where you've signed in, scripts can run pw commands directly. Use pw api for API calls; it selects the platform and handles authentication:

pw api buckets

For a tool that needs a bearer token, pw auth token --print prints the current credential, renewing a browser or device sign-in if needed. See the curl example.

Access tokens are short-lived, so print a new one each time rather than saving it. With -o json, pw auth token --print prints the token with its type and the seconds it has left:

{"access_token": "pwoa_...", "token_type": "Bearer", "expires_in": 3599}

The Go, Python, and TypeScript SDKs automatically handle OAuth access tokens and renewal through your saved sign-in when created from credential config. Your application does not need to copy tokens or implement refresh logic. Passing a copied token to a client, or exporting it as PW_API_KEY, does not renew it. Follow the long-running script guidance before starting work that may outlast a token.

API keys

For CI and other automation that runs without you, use an API key. By default, a key's chosen expiration must be within 730 days. Your organization or platform policy can change that limit; non-expiring keys require an Unlimited policy. Keys never renew automatically, so replace them before expiration. Set the PW_API_KEY environment variable to the key, which takes precedence over the credentials file, or pipe it to pw auth to save it as a context:

pw auth < key.txt

Avoid passing a key as a command-line argument, where other users on a shared machine can see it. Saving a token with pw auth token <token> is deprecated; use pw auth < key.txt instead.

Use pw auth --with-api-key to paste an API key even when the CLI knows the platform host. For a one-off job, the Token option in Account > Authentication creates a short-lived API key lasting 1–24 hours.

Where the CLI stores files

The PW CLI keeps your settings, credentials, and other per-user data in standard XDG base directories. The layout is identical on Linux, macOS, and Windows, so the same paths work whether you're on a laptop or a login node.

Config directory

~/.config/pw/ holds the files you'd want to keep or back up. It is created with owner-only permissions because it contains your credentials.

pw code also reads portable agent files that other agent tools can share, outside the pw directory:

Cache and state directories

~/.cache/pw/ holds regenerable data that is safe to delete, such as images (code-images/) and long text (code-pastes/) you paste into pw code.

~/.local/state/pw/ holds pw code's working state:

Files named for the host keep login nodes that share a home directory from colliding.

Changing where files are stored

Set the standard XDG environment variables to relocate any of the three directories:

• XDG_CONFIG_HOME: moves the config directory (default ~/.config)
• XDG_CACHE_HOME: moves the cache directory (default ~/.cache)
• XDG_STATE_HOME: moves the state directory (default ~/.local/state)

To keep credentials in a separate directory, set PW_CREDENTIALS_DIR to an absolute directory path. The CLI uses $PW_CREDENTIALS_DIR/.credentials, including the leading dot, instead of the normal credentials filename. It takes precedence over XDG_CONFIG_HOME; setting it does not move an existing file or fall back to your usual contexts. See credential-directory recipes for separate scripts, temporary jobs, containers, and shared home directories.

Files written elsewhere

A few commands add files to the conventional locations their tools expect, outside the pw directories:

When you run pw code inside a project, it also reads project-scoped configuration from that project: .mcp.json, .agents/settings.json, the repository root's .agents/settings.local.json, and definitions under .agents/agents/, .agents/commands/, and .agents/skills/. Custom commands in .pw/code/commands/ are still read. See Settings.

About URIs

When using the CLI to interact with buckets, you will see them identified by a Uniform Resource Identifier (URI).

URIs function similarly to URLs. In fact, URLs are a type of URI. URIs, however, do not have to point to a location on a network; they only serve to identify a resource.

In the screenshot below, we used the PW CLI to list our buckets in a table format. Each bucket has a URI that's exclusive to the ACTIVATE platform, which takes the form of pw://namespace/bucket.

There is also a URI that's exclusive to a bucket's CSP, such as:

• gs://google-bucket-name
• s3://aws-bucket-name
• https://azure-bucket-name.blob.core.windows.net/azure-bucket-name

Buckets will only display a CSP URI if they have already been provisioned.

A screenshot of provisioned buckets, displayed in a terminal as a table