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.

For cloud clusters, you must first authenticate either with an API key or a token.

API Key

First, create an API key by following these instructions in our user guide.

Next, use the pw auth command by following these instructions, then paste your API key when prompted.

Token

First, create a token by following these instructions in our user guide.

Next, use the pw auth command by following these instructions, then paste your token when prompted.

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`	The API key or token used to authenticate. 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