About the PW CLI | User Guide

The Parallel Works command-line interface (PW CLI) offers a streamlined way to interract 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

PATH Configuration

If ~/.local/bin is not already on your PATH, the installer will provide instructions for adding it.

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.

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 access automatically while you use it. 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. For a tool that needs an access token, pw auth token --print prints a current one, renewing the sign-in if needed:

curl -H "Authorization: Bearer $(pw auth token --print)" https://cloud.parallel.works/api/buckets

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 use your sign-in the same way and renew it automatically.

API keys and tokens

For CI and other automation that runs without you, use an API key. Every API key expires, by default within 730 days. 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.

If the CLI doesn't know the platform host, or the platform doesn't support browser sign-in, pw auth prompts you to paste an API key or token instead.

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.

Location	Path	What's stored
Config	`~/.config/pw/`	Settings and credentials
Cache	`~/.cache/pw/`	Regenerable data such as pasted images
State	`~/.local/state/pw/`	Session history and transcripts

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.

File	What's stored
`settings.json`	CLI preferences, including your saved `pw code` model, allocation, and permission mode
`credentials`	Your saved contexts and the sign-in, API key, or token each one uses. Never share or commit this file
`code/commands/`	Your personal `pw code` slash-command definitions (one Markdown file per command)

Cache and state directories

~/.cache/pw/ holds regenerable data that is safe to delete, such as images you paste into pw code. ~/.local/state/pw/ holds your pw code conversation transcripts (code-sessions/) and per-directory prompt history (code-history/).

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 move only your credentials, set PW_CREDENTIALS_DIR to the directory that should hold the credentials file. This takes precedence over XDG_CONFIG_HOME.

Upgrading from an older CLI

Earlier releases stored these files under ~/pw/ (for example ~/pw/settings.json and ~/pw/.credentials). The CLI moves them to the locations above automatically the first time you run it, so there's nothing you need to do.

Files written elsewhere

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

Path	Written by	What's stored
`~/.ssh/pwcli`, `~/.ssh/pwcli.pub`	`pw ssh`, `pw vscode`	The SSH key pair used to connect to your resources
`~/.ssh/pw_config` (and an `Include pw_config` line in `~/.ssh/config`)	`pw vscode`	Per-resource SSH host entries
`~/.kube/config` (or `$KUBECONFIG`)	`pw kube auth`	Cluster, credential, and context entries added through `kubectl`

When you run pw code inside a project, it also reads project-scoped configuration from that project's directory: <project>/.pw/code/settings.json, settings.local.json, and any custom commands under <project>/.pw/code/commands/.

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.

Screenshot of buckets listed in a terminal on the ACTIVATE platform.

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