# About the PW CLI

> Source: https://parallelworks.com/docs/cli

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:

```bash
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:

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

:::info 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.

**Linux, AMD**

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

**Linux, ARM**

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

**macOS, Apple Silicon**

```bash
mkdir -p ~/bin
wget "https://activate.parallel.works/cli/pw-darwin-arm64" -O ~/bin/pw
echo 'export PATH="$PATH:$HOME/bin"' >> ~/.zshrc # adjust if not using zsh
```

**macOS, Intel**

```bash
mkdir -p ~/bin
wget "https://activate.parallel.works/cli/pw-darwin-amd64" -O ~/bin/pw
echo 'export PATH="$PATH:$HOME/bin"' >> ~/.zshrc # adjust if not using zsh
```

**Windows, AMD**

```powershell
$dest = "$env:LOCALAPPDATA\Programs\pw"
New-Item -ItemType Directory -Force -Path $dest
curl.exe -L "https://activate.parallel.works/cli/pw-windows-amd64.exe" -o "$dest\pw.exe"
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$dest", [EnvironmentVariableTarget]::User)
```

**Windows, ARM**

```powershell
$dest = "$env:LOCALAPPDATA\Programs\pw"
New-Item -ItemType Directory -Force -Path $dest
curl.exe -L "https://activate.parallel.works/cli/pw-windows-arm64.exe" -o "$dest\pw.exe"
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$dest", [EnvironmentVariableTarget]::User)
```

## 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](/docs/account-settings/authentication#managing-api-keys) in our user guide.

Next, use the `pw auth` command by following [these instructions](/docs/cli/pw/auth), then paste your API key when prompted.

#### Token

First, create a token by following [these instructions](/docs/account-settings/authentication#managing-tokens) in our user guide.

Next, use the `pw auth` command by following [these instructions](/docs/cli/pw/auth), 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](https://specifications.freedesktop.org/basedir-spec/latest/). 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`.

:::note 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.](/content-images/docs/cli/cli-buckets-running-table.png?v=8d10403c)
_A screenshot of provisioned buckets, displayed in a terminal as a table_