# Parallel Works Documentation
> Parallel Works ACTIVATE is a hybrid, multi-cloud platform for running high-performance computing (HPC) and AI workloads across on-premises and cloud resources. This file indexes the documentation — the PW command-line interface (CLI), the REST API, and the user guides — for AI agents and tools. Append `.md` to any /docs URL to fetch that page as clean markdown.
# About ACTIVATE
> Source: https://parallelworks.com/docs/about-activate
# About ACTIVATE
## What We Do
The ACTIVATE control plane gives users the ability to create and manage elastic resource pools and high-performance computing (HPC) clusters on virtually any cloud service provider. ACTIVATE is designed to be accessible and universally useful: users can run scripts—called _workflows_—that are defined in a variety of programming languages across multiple pools and clusters.
ACTIVATE customers use their own cloud accounts to deploy cloud HPC resources via the ACTIVATE control plane, meaning that HPC resources are our customer-deployed solution. While ACTIVATE can be deployed in different locations (i.e., in the cloud or on-premises), it is not deployed by customers directly.
Our goal is to make high-performance simulation and modeling computation as simple as possible, and we're working towards that goal every day.
## Working With Cloud Resources
The process for using cloud resources typically follows these steps:
- Log in to ACTIVATE.
- Create or start a cluster with the configuration that best suits your work.
- Transfer your data to the cloud from an on-premises location or from an object storage, such as Amazon Web Services (AWS) S3 buckets, Google Cloud Storage (GCS) buckets, or Microsoft Azure Blob containers.
- Complete your computations.
- Transfer your data back to an on-premises location or to object storage.
- Shut down the cluster.
If you've never used ACTIVATE before, you can check out [our **Getting Start** tutorial](/docs/getting-started) to learn more about using clusters.
## Essential Cloud Concepts
**Clusters** are standard HPC clusters well-suited for supporting the execution of a wide range of parallel applications, including MPI, OpenMP, and GPU-based applications as well as various hybrid combinations. Cloud-based clusters can run a variety of job schedulers, providing an environment that’s familiar to users of traditional HPC clusters. On ACTIVATE, a cluster has one controller node that sends jobs to the compute nodes, which are grouped into partitions.
**Workflows** are scripts written in a variety of languages and programming models. Typically, workflows orchestrate the execution of applications relevant to your domain, whether that’s computational fluid dynamics for mechanical engineers or molecular modeling for biochemists. Workflows are run on either pools or clusters, depending on the need of the workflow. There are several demonstration and template workflows available in the ACTIVATE Marketplace (see [**Marketplace**](/docs/marketplace) for more information).
## About This Guide
We constantly update the ACTIVATE control plane, adding features to make it easier to complete large-scale projects. Our documentation is a work in progress: the following instructions and information will be updated regularly as we work to improve ACTIVATE and our users’ experience.
We would love to hear your feedback. Feel free to share your requests for additional features and thoughts about ACTIVATE at [feedback@parallelworks.com](mailto:feedback@parallelworks.com).
# Account Settings
> Source: https://parallelworks.com/docs/account-settings
# Account Settings
Manage your personal account preferences and settings in ACTIVATE.
## Settings Areas
### [Authentication](/docs/account-settings/authentication)
Manage your authentication credentials:
- SSH keys for cluster access
- SSH private keys for connecting to remote resources
- API keys for programmatic access
- Token generation
- Multi-factor authentication (2-Step Verification)
### [Cloud Snapshots](/docs/account-settings/cloud-snapshots)
Create and manage snapshots of your cloud resources for backup and recovery.
### [Connections](/docs/account-settings/connections)
Link your GitHub account to enable repository access on the platform.
### [Customizing Layouts](/docs/account-settings/customizing-layouts)
Personalize your ACTIVATE workspace:
- Customize your home dashboard widgets
- Configure sidebar navigation preferences
### [Language](/docs/account-settings/language)
Choose your preferred language for the ACTIVATE interface.
### [Managing Notifications](/docs/account-settings/managing-notifications)
Control how and when you receive notifications about your resources and workflows.
### [Resetting Password](/docs/account-settings/resetting-password)
Update your account password when needed.
### [Restarting Your Workspace](/docs/account-settings/restarting-your-workspace)
Restart your user workspace if you encounter issues.
### [Workflow Variables](/docs/account-settings/workflow-variables)
Define personal variables for use in workflow expressions.
## Quick Links
- [Authentication](/docs/account-settings/authentication) - Manage SSH and API keys
- [Customizing Layouts](/docs/account-settings/customizing-layouts) - Personalize your dashboard
- [Managing Notifications](/docs/account-settings/managing-notifications) - Configure alerts
# Authentication
> Source: https://parallelworks.com/docs/account-settings/authentication
# Authentication
## Managing API Keys
You can use an API key to access Parallel Works via its REST API.
:::info Note
Please note that API keys act as an alternate means to access your account and should be treated with the same care as your login password.
:::
### Create an API Key
Navigate to your account settings (**Username** > **Account**).
On the next page, click **Authentication**.
Click **API Keys**.
Click **Add Key**.
Enter a **Key Name** for the new API key.
If your organization permits users to select their own expiration date for API keys, use the **Expiration** dropdown menu to select when your key will expire. You can choose no expiration or a date in 7, 30, 60, or 90 days. Shorter expiration periods are more secure.
Click **Add Key**.
Your new API key will be displayed on the next page. You can use the copy button to copy and save the key in a secure place. Once you refresh or navigate away from this page, you won’t be able to see the key again.
### Delete an API Key
Navigate to **Account** > **Authentication** > **API Keys** and click the delete icon to remove an API key from your ACTIVATE account.
A dialog box will appear with more information about deleting your key. Click **Delete API Key** to confirm the deletion. The key will be removed from your account immediately.
## Managing Tokens
You can create a short-term token and use it to authenticate our CLI after installing locally. These tokens last 24 hours, after which you will need to re-authenticate.
### Create a Token
Navigate to your account settings (**Username** > **Account**).
On the next page, click **Authentication**.
Click **API Keys**.
Click **Generate Token**.
If your organization permits users to select their own expiration date for tokens, use the **Expiration** dropdown menu to select when your key will expire. You can choose from 1 hour up to 24 hours in 1-hour increments. Shorter expiration periods are more secure.
Click **Add Token**.
Your new token will be displayed on the next page. You can use the copy button to copy and save the key in a secure place. Once you refresh or navigate away from this page, you won’t be able to see the key again.
## Managing SSH Keys
You can add an SSH key to your ACTIVATE account, which will allow you to log in to any active cluster from any device with that SSH key on it.
### Create an SSH Key
Navigate to your account settings (**Username** > **Account**).
On the next page, click **Authentication**.
Click **SSH Keys**.
Click **Add Key**.
Use the **Key Name** field to give the key a unique name. Paste your public SSH key in the **Key** field.
Click **Add Key**.
You can now log in to any active cluster. Navigate to the terminal or command line on your device and enter `ssh -i /path/to/ssh/private/key username@IPaddress`:
```shell
parallelworks@Parallels-Macbook-Air sshtest % ssh -i ./id_rsa demo@34.135.24.147
Last failed login: Thu Mar 2 09:48:20 UTC 2023 from 60.94.197.104.bc.googleusercontent.com on ssh:notty
[demo@democluster-70 ~]$
```
### Copy an SSH Key
In **Account** > **Authentication** > **SSH Keys**, click the clipboard icon to copy your SSH key to your computer's clipboard.
## Managing SSH Private Keys
You can store private SSH keys on your ACTIVATE account, which the platform uses on your behalf to connect to remote resources — for example, existing clusters that require an SSH credential you already hold.
Unlike the public SSH keys described above (which let you log in *to* your clusters), private keys let ACTIVATE log in *from* the platform to a remote resource.
### Create an SSH Private Key
Navigate to your account settings (**Username** > **Account**). On the next page, click **SSH Private Keys**.
Click **New SSH Private Key**.
Use the **Name** field to give the key a unique name, and optionally add a **Description**. Paste your private key in the **Remote Resource SSH Private Key** field.
Click **Create SSH Private Key**. A dialog box with the message _SSH Private Key created successfully_ will appear, and the key will be listed with its account name, description, and creation date.
### Delete an SSH Private Key
In **Account** > **SSH Private Keys**, click the delete icon in the key's row. A dialog box will appear; click **Delete credentials** to confirm.
## Managing Multi-Factor Authentication
You can add a second verification step to your account. With 2-Step Verification turned on, signing in requires a code from an authenticator app in addition to your password.
### Turn On 2-Step Verification
Navigate to your account settings (**Username** > **Account**). On the next page, click **Authentication**.
Click the **2-Step Verification** row, which shows whether 2-Step Verification is currently on or off.
On the **Manage MFA Settings** page, find the **Authenticator app** card and click **Use Authenticator**.
On the **Setup Authenticator App** page, use a phone app like 1Password, Authy, Google Authenticator, or Microsoft Authenticator to scan the QR code. If you can't scan the QR code, click **Can't scan the QR code?** to reveal a secret key you can enter in your app manually.
Enter the 6-digit code from your app in the **Verification code** field and click **Enable 2FA**. A dialog box with the message _MFA setup successful_ will appear.
The next time you sign in, you'll be asked for a code from your authenticator app after entering your password.
:::note Feature Preview
Security keys (WebAuthn) are also available as an MFA method through a Feature Preview. Organizations can require them with the [**Enforce Security Key MFA**](/docs/organization-admin/settings/policies) policy.
:::
### Turn Off 2-Step Verification
Navigate to **Account** > **Authentication** > **2-Step Verification**.
To remove your authenticator app, click the delete icon on its card. A dialog box will appear; click **Remove Authenticator app** to confirm. Your authenticator will be removed immediately.
To turn off 2-Step Verification entirely, click **Turn Off**. A dialog box will appear; click **Turn off 2-Step Verification** to confirm.
# Working With Cloud Snapshots
> Source: https://parallelworks.com/docs/account-settings/cloud-snapshots
# Working With Cloud Snapshots
Cloud snapshots let you make persistent changes to the operating system image running on your cluster nodes. By using an image provided by Parallel Works as a base, you can stage automations, install additional software, or enable additional services.
## Creating Cloud Snapshots
Navigate to your account settings (**Username** > **Account**).
On the next page, click **Cloud Snapshots**.
In **Cloud Snapshots**, click **New Snapshot**.
### Snapshot Configuration Settings
There are several configurable parameters for cloud snapshots, which are outlined below.
#### Type
Use this dropdown menu to select whether your snapshot will be built for AWS, Azure, or Google.
#### Cloud Account
Use this dropdown menu to select which cloud account will provision your snapshot. For most users, this menu should be left as the default option, unless you're a member of multiple organizations.
#### Group
Use this dropdown menu to select the group name that your organization uses to allocate costs. This menu is especially important if your organization uses multiple groups.
If you’re not sure which group to select, you can contact us or your organization’s ACTIVATE administrator.
#### Snapshot Region
Use this dropdown menu to select the region your snapshot will be provisioned in.
If you run in multiple regions, you will want to provision the snapshot wherever you run your clusters.
#### Base Image
Use this dropdown menu to select the ACTIVATE image that will be the base for your snapshot. Typically, this menu will be populated with the suggested version by default.
#### Root Disk Size (GB)
Use this field to enter the size of the snapshot's root disk. By default, this field is set to `100`. Typically, you won't have to change this value unless you run into capacity issues.
#### Name
Use this field to enter the name of your snapshot as it will be listed on the ACTIVATE control plane.
#### Description
Use this field to enter a description to provide additional details about your snapshot.
### Snapshot Build Script
You can enter a script in **Snapshot Build Script**, which will run to make additions to the base ACTIVATE image. You can use this script to install additional packages from `yum` repositories, clone GitHub repositories, or download files from a URL. An example build script is provided below.
```bash
#!/bin/bash
# Get useful environment info
echo "my username is $USER"
echo "my home dir is $HOME"
echo "my workdir is $PWD"
# Clone a public GitHub repository
git clone https://github.com/hpc/ior.git /usr/local/src/ior;
# Install Anaconda and have it initialize on login
wget https://repo.anaconda.com/archive/Anaconda3-2023.03-Linux-x86_64.sh;
sh ./Anaconda3-2023.03-Linux-x86_64.sh -b -p /usr/local/anaconda3;
# Symlink the Conda executable to the main /usr/local/bin directory
ln -s /usr/local/anaconda3/bin/conda /usr/local/bin/conda;
# Install Jupyter
conda install -y jupyter;
# Packages will be installed under the Anaconda root directory, so symlink what you need
ln -s /usr/local/anaconda3/bin/jupyter-lab /usr/local/bin/jupyter-lab;
ln -s /usr/local/anaconda3/bin/jupyter /usr/local/bin/jupyter;
# Install R and R Studio Server
# Specify the R version you want
# Download and install R packages
curl -O https://cdn.rstudio.com/r/centos-7/pkgs/R-${R_VERSION}-1-1.x86_64.rpm;
yum -y install R-${R_VERSION}-1-1.x86_64.rpm; # NOTE: this package installs R to /opt/R/4.1.3/bin/R
# Install R Studio packages
wget https://download2.rstudio.org/server/centos7/x86_64/rstudio-server-rhel-2023.03.0-386-x86_64.rpm;
yum -y install rstudio-server-rhel-2023.03.0-386-x86_64.rpm;
```
This build script will:
- print some basic environment information.
- clone the public [IOR](https://github.com/hpc/ior) repository from GitHub into `/usr/local/src/ior`.
- download and run the `Conda` installer.
- download and install R and R Studio Server.
- link executables to a common `$PATH` location.
Once you’ve provided your build script, click **Create Snapshot** to save the configuration.
## Provisioning Cloud Snapshots
After clicking **Create Snapshot**, the page will update with a **Provisioning Log** and two new buttons: **Save Snapshot Config** and **Provision Snapshot**.
Click **Save Snapshot Config** when making configuration changes that you want to save, including changes to the main parameters.
Click **Provision Snapshot** to start building the snapshot image. Doing so will replace the **Snapshot Build Script** with the **Provisioning Log**, where you can monitor the snapshot build.
The snapshot build process works by creating a temporary virtual machine (VM) that runs the ACTIVATE base image. Then, the provided script runs to make additions to the image, which is saved as a separate snapshot.
When the snapshot is done building, the **Provisioning Log** will show a message identifying the name of the image in the CSP account. If there were errors in the build that prevented it from completing, those will also be visible in the log.
If your build is successful, the **Provisioning Log** will show a message such as:
```json
Packer build completed successfully
{"snapshot_id":"ami-0a5854d925e6e558b", "snapshot_name":"pw-Demo-hello", "csp":"aws", "region":"us-east-1" }
https://parallel.works/api/v2/machineimages
```
If your build is unsuccessful, the **Provisioning Log** will show a message such as:
```json
Build 'amazon-ebs.aws' errored after 1 minute 57 seconds: Script exited with non-zero exit status: 1. Allowed exit codes are: [0]
==> Wait completed after 1 minute 57 seconds
==> Some builds didn't complete successfully and had errors:
--> amazon-ebs.aws: Script exited with non-zero exit status: 1. Allowed exit codes are: [0]
==> Builds finished but no artifacts were created.
Packer build failed
```
:::info Note
If you reprovision an existing snapshot and the new build has errors, your previously working snapshot will not be overwritten.
:::
## Using Cloud Snapshots
Snapshots you have created for any CSP will automatically be added to your cluster configuration settings. You can see user-created snapshots on a cluster's configuration page by selecting the [**Image**](/docs/compute/configuring-cloud-clusters#image) in **Controller Settings** and the [**Elastic Image**](/docs/compute/configuring-cloud-clusters#elastic-image) in **Partition Settings**.
You can also configure a different snapshot for your controller and each of your partitions.
## Deleting Cloud Snapshots
To delete a custom snapshot, navigate to its configuration page and click **Deprovision Snapshot**.
A dialog box will appear with the message _Are you sure you want to deprovision the snapshot test?_
Click **Deprovision snapshot**. The **Provisioning Log** will then display the deletion process:
```json
Starting delete of custom image...
CLOUD: aws
REGION: us-east-1
PROJECT: ca-cloudmgmt
IMAGE: pw-Demo-hello
AMI: ami-023b3386461fdfad6
SnapshotId: snap-01d59ca427982c1d8
aws ec2 deregister-image --image-id ami-023b3386461fdfad6
aws ec2 delete-snapshot --snapshot-id snap-01d59ca427982c1d8
Delete completed...
```
If you use the method above, you will still have your snapshot listed in **Cloud Snapshots** (**Username** > **Account** > **Cloud Snapshots**), and you will be able to reconfigure and reprovision the snapshot at any time.
Alternatively, you can delete a snapshot from the list in **Cloud Snapshots**. If you click the delete icon, a dialog box will appear with the message _Are you sure you want to delete the snapshot [snapshot name]?_
Clicking **Delete snapshot** will permanently remove the snapshot from your account and from the list in **Cloud Snapshots**.
:::info About Deletion
If you want to delete a snapshot from the list in **Cloud Snapshots**, you first need to deprovision the snapshot on its configuration page. If you don't, the snapshot will still exist in your CSP account.
:::
# Connections
> Source: https://parallelworks.com/docs/account-settings/connections
## About Connections
The **Connections** page links your GitHub account to ACTIVATE, enabling repository access on the platform.
:::info Note
GitHub connections are available once a platform administrator has configured the platform's GitHub integration. If the **Link GitHub** option isn't available, contact your administrator.
:::
## Link Your GitHub Account
Navigate to your account settings (**Username** > **Account**). On the next page, click **Connections**.
On the GitHub card, click **Link GitHub**. A GitHub authorization window will open; follow the prompts to authorize the connection.
Once linked, the card shows **Connected as @username**, and a dialog box with the message _GitHub account linked successfully_ will appear.
## Install the GitHub App
After linking your account, install the GitHub App wherever you want to grant repository access:
- The **Connected organizations** section lists the GitHub organizations where the app is installed, along with each installation date. Click the plus icon to install the app on another organization.
- The **Personal GitHub account** section shows whether the app is installed on your personal account.
To manage an existing installation's repository access, open its **Connected** dropdown menu and click **Configure in GitHub**.
## Disconnect Your GitHub Account
On the GitHub card, click the delete icon. A dialog box will appear with the message _Are you sure you want to disconnect your GitHub account? You will need to re-link to access repositories._
Click **Disconnect**. A dialog box with the message _GitHub account disconnected_ will appear.
# Customizing Layouts
> Source: https://parallelworks.com/docs/account-settings/customizing-layouts
# Customizing Layouts
You can customize both your Dashboard and your sidebar layouts by adding, removing, and reordering items.
## Customizing the Dashboard
On the **Dashboard**, click ** Customize**.
### Move Modules
Move your cursor over a module until it becomes the directional arrows icon. Click to drag and drop a module anywhere in the grid.
### Resize Modules
Move your cursor to the bottom-right corner of a module until it becomes the diagonal arrow icon. Click, drag, and drop the corner to resize the module.
### Rename Modules
Click the edit icon.
Enter a new name for the module. Click the checkmark icon.
### Add Modules
Click **+ Add Widget**.
A panel will appear with the available modules. Click, drag, and drop a module into the grid to add it.
### Delete Modules
Click the delete icon.
### Filter Data
Some modules allow for further customization. Click the menu icon.
The available options will depend on the module. For example, some modules allow filtering the data they display.
After making your changes, click the menu icon again.
### Restore Defaults
If you want to revert your changes, click ** Restore defaults**.
### Save Changes
When you're done making changes, click ** Done**.
## Customizing the Sidebar
At the bottom of the sidebar, click the gear icon. Alternatively, navigate to **Account** > **Sidebar**.
In **Sidebar Settings**, you can uncheck boxes to remove items. Click **Reset to default** to undo your changes.
:::info Note
Please note that your administrator can remove items from the default sidebar's options. You may not have access to all of the items in the screenshot above.
:::
# Language
> Source: https://parallelworks.com/docs/account-settings/language
## About Language Settings
You can choose your preferred language for the ACTIVATE interface. The platform currently supports:
- English
- Español (Spanish)
- 日本語 (Japanese)
- 한국어 (Korean)
- 中文 (Chinese)
## Changing Your Language
Navigate to your account settings (**Username** > **Account**). On the next page, click **Language**.
Under **Language Setting**, use the dropdown menu to choose your preferred language. The **Current Language** section shows which language is currently active.
Click **Save Language**. A dialog box with the message _Language setting saved_ will appear, and the interface will switch to your selected language immediately.
# Managing Notifications
> Source: https://parallelworks.com/docs/account-settings/managing-notifications
# Managing Notifications
The ACTIVATE control plane includes a customizable notification system for both our web interface and your ACTIVATE-linked email address.
Navigate to your account settings (**Username** > **Account**).
In **Profile Settings**, click **Notifications**.
Here, you can manage past notifications as well as configure your notification settings.
You can also reach the **Notification Hub** by clicking the bell icon in the navigation bar, then clicking **Show More**.
## Changing Notification Settings
Scroll down to the **Manage notifications** section.
You can select how you would like to receive your notifications here. **Web** notifications appear under the bell icon and in the **Notification Hub** on the ACTIVATE control plane. **Email** notifications are sent directly to your ACTIVATE-linked email address.
By default, all options for **Workflow**, **Scheduler**, and **Platform** notifications are enabled as **Web** notifications. Click the checkboxes for **Web** and **Email** to enable or disable notifications.
For more customized settings, you can click a notification type and enable or disable its sub-types.
When you’re done, click **Save notification settings**.
## About Notification Types
Our notification system includes the types outlined below.
- Workflows
- **Job Fail**: If a workflow fails during start-up or run-time, this notification will be triggered.
- **Ready Interactive Workflow**: Because interactive workflows can have longer start-up times, we’ve included this notification to send when an interactive session is ready to use.
- Scheduler
- **Job Start/Finish**: Job status notifications will be sent from the scheduler’s prolog and epilog scripts. This method requires no cluster side user action, and will send notifications about your jobs when selected.
- **—mail-type**: This notification uses the Slurm flag `--mail-type`, which is set by the user on the cluster in order to send notifications when certain events occur. This method requires users to enter the `--mail-type` flag when calling `salloc`, `sbatch`, `srun`, or in their job scripts. For more information about these Slurm commands, please see [**Submitting Jobs via Slurm**](/docs/compute/submitting-jobs#notification-management).
- Platform
- **General Notification**: These notifications include cluster start-up messages and run-time errors.
# Resetting Your Password
> Source: https://parallelworks.com/docs/account-settings/resetting-password
# Resetting Your Password
Navigate to your account settings (**Username** > **Account**).
On the next page, click **Authentication**.
Click **Password**.
On the next page, enter your current password and your new password.
Your new password must contain:
- at least 15 characters
- one lowercase character
- one uppercase character
- one number
- one special character
When you're done, click **Update Password**.
# Restarting Your Workspace
> Source: https://parallelworks.com/docs/account-settings/restarting-your-workspace
# Restarting Your Workspace
Your user workspace is your dedicated environment for starting clusters, running workflows, and accessing your data on the ACTIVATE control plane. Each user’s workspace is separate from each other, so the work you do on ACTIVATE will never affect another user’s work.
This page explains how to restart your user workspace, which is useful if you’re experiencing issues like a cluster that won’t start or a workflow that won’t run.
:::info Note
All running clusters and jobs will be disrupted if you restart your workspace.
:::
Navigate to your account settings (**Username** > **Account**).
In your profile settings, click **Restart Workspace**.
A dialog box will appear with the message *Are you sure you want to restart your workspace?*
Click **Restart**. After the workspace has restarted, you’ll see the message _User workspace killed_.
:::info Troubleshooting
If you restarted your workspace because you were experiencing errors and they aren’t resolved after restarting, please contact us or your ACTIVATE administrator.
:::
# Workflow Variables
> Source: https://parallelworks.com/docs/account-settings/workflow-variables
## About Workflow Variables
You can define personal variables for use in workflow expressions. Variables you create here are available in your workflows through the `var` context — for example, `${{ var.MY_VARIABLE }}`.
Personal variables are separate from your organization's variables, which use the `org` context and are managed by organization admins. For more information, please see [**Organization Workflow Variables**](/docs/organization-admin/settings/variables).
## Adding a Variable
Navigate to your account settings (**Username** > **Account**). On the next page, click **Variables**.
Click **Add variable**.
In the dialog box that appears, enter a **Key** (letters, numbers, underscores, and hyphens only — for example, `MY_API_KEY`) and a **Value**. Click **Save**. A dialog box with the message _Variable created_ will appear.
Variables are stored as secrets by default: their values are masked in the variables table and can't be viewed again after saving.
## Editing and Deleting Variables
To change a variable's value, click the edit icon in its row, enter the new **Value**, and click **Save**. A variable's key can't be changed after creation; to rename a variable, delete it and create a new one.
To delete a variable, click the delete icon in its row. A dialog box will appear; click **Delete** to confirm.
## Using Variables in Workflows
Reference your variables in any workflow definition with the `var` context:
```yaml
jobs:
main:
steps:
- name: Run
run: echo ${{ var.MY_VARIABLE }}
```
For more information about contexts and expressions, please see [**Inputs and Expressions**](/docs/run/workflows/building-workflows/inputs-and-expressions).
# Navigating the Admin Panel
> Source: https://parallelworks.com/docs/admin-panel
## About the Admin Panel
This page explains the features in the **Admin Panel**, which you can access by clicking your username and selecting **Admin**.
:::info Persona
You’ll only be able to access these features if you’re an ACTIVATE platform administrator.
:::
:::info About Containers
In much of the user guide, we say “user workspaces” to talk about a user’s account on the ACTIVATE platform. Please note that this term is synonymous with “user container,” which we use on this page.
:::
## Platform Settings
When you navigate to the **Admin Panel**, you’ll see **Platform Settings** by default. This tab displays essential information about your organization’s version of the platform.
When making changes on this page, click **Save Platform Settings**. Your changes will be applied immediately.
#### License Information
The **Information** section at the top of the page displays details that cannot be configured from within the platform: the **Status URL**, **Platform version**, and **Platform License**. If a license expiration date or licensed features are set, they're displayed here as well.
If a license has not been set, resources will not be able to be started until one is added.
To upload a new license, click **Update Platform License**. In the dialog box that appears, paste the license in the **New License** field and click **Update License**.
#### Platform Name
This field sets the display name shown on the login page. If it's not set, _Parallel Works ACTIVATE_ is used.
#### Maintenance Message
If you set a maintenance message, it will show as an alert on all pages of the platform. You can use this field to warn users about an upcoming maintenance window before enabling **Maintenance Mode**.
#### Maintenance Mode
While **Maintenance Mode** is enabled, only admins will be able to start and stop resources.
To enable **Maintenance Mode**, click the checkbox next to it.
The platform will remain in maintenance mode until you deactivate it.
#### Forgot Password Enabled
While this option is enabled, the forgot password feature is available on the platform, and users can request a password reset from the login page.
#### API Key Expiration
By default, users can customize the expiration date for their created API keys with no expiration or a date in 7, 30, 60, or 90 days.
You can change the maximum number of days for API keys to expire. For example, if you set this date to 30 days, users may not create a key that expires after 60 days.
To make this change, check the box for **Enforce Maximum API Keys TTL** (Time to Live) and enter a number in the **Days** field that appears.
#### Single Organization Platform
If you check this box, other users will only see login options for the organization your account belong to.
#### Enable Onboarding
When this option is enabled, new users will be guided through an onboarding flow on first login. During onboarding, users can add the compute resources and workflows recommended by their organization. For more information, please see [**Onboarding**](/docs/organization-admin/customize/onboarding).
#### Create k8s PVC
This option creates a PersistentVolumeClaim (PVC) in users' home directories. For more information about PVCs, please see [this page](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) of Kubernetes's documentation.
#### Delete User Files on Deletion
When this option is enabled, user files and SSH keys will be deleted from their workspace when their account is deleted.
#### Minimum Agent Version
Use this field to reject agent tunnel connections below a minimum version (e.g., `v7.45.2`). Already-connected agents below the minimum are disconnected on the next sweep. Leave the field empty to disable enforcement.
#### Docker Workspace Settings
Use this field to change Docker workspace settings, such as additional mounts, variables, and Domain Name System (DNS) settings.
### Workspace Defaults
The **Workspace Defaults** section sets the default workspace configuration for the platform. These defaults are applied to user workspaces unless an organization or user has set their own. Leave a numeric field blank to use the built-in default.
- **Workspace Type**: the container runtime new users will be provisioned on (**docker** or **k8s**)
- **Workspace Image**: the container image for user workspaces; leave blank to use the upstream image
- **Default User Host**: the host new Docker workspaces are provisioned on
- **Default CPU Request** and **Default CPU Limit**: measured in cores
- **Default Memory Request** and **Default Memory Limit**: measured in GB
- **Default Ephemeral Storage Limit**: measured in GiB
When making changes in this section, click **Save Workspace Defaults**. Your changes will be applied immediately.
## Users
This tab displays all of your users’ information, including:
- username
- email address
- enabled status
- workspace image
- account creation date
Use the **Username** field to search for users.
Use the **Enabled/Disabled** dropdown menu to display users that are enabled, disabled, or either. This option is set to **Enabled/Disabled** by default.
Use the **Limit** dropdown menu to narrow the listed users to 10, 20, 50, 100, or All. This option is set to **50** by default.
### Editing User Information
In the **Users** tab, click on the username you’d like to edit.
On the next page, you can edit several of the user’s parameters.
The first section contains information about the user’s account, container, and access to the platform.
#### Identity
Here, you can edit a user’s **Username** or **Email**. Altering either of these parameters will change the user’s login credentials.
#### Settings
Here, you can control a user’s access to the platform.
#### User Host
This field identifies the user host, which is the part of the platform where account resources are provisioned.
We recommend contacting us before you make changes to this parameter.
#### User Container
This option identifies which service will be used to deploy a user’s container.
Use the bubbles to select **Docker** or **k8s** (Kubernetes).
We recommend contacting us before you make changes to this parameter.
#### MFA Enabled
Use the bubbles to select whether the user will use multi-factor authentication.
Select **No** if a user doesn’t need multi-factor authentication.
Select **Duo** if you work with a company or organization that is not affiliated with the government. Duo is a Cisco service that is more popular with other types of institutions.
Select **MyProxy** if you work with a governmental agency, such as a public university or a research organization. Generally, MyProxy is preferred for these types of institutions.
We recommend contacting us before you make changes to this parameter.
#### User Workspace Image
This field identifies which image version a user’s workspace is running.
#### User Organization
Use this dropdown menu to assign the user to an organization.
#### Attributes
Here, you can control whether a user is an **Admin** or **Active** by selecting their respective checkboxes.
A user with **Admin** enabled will be able to access the **Admin Panel** and all of its settings. This option does not affect the group setting `org:admin`. For more information, please see [**About Roles**](/docs/organization-admin#about-group-roles).
A user with **Active** enabled will be able to log in to the platform with their username and password. Unchecking **Active** will disable a user’s access to the platform.
Users who are **Active** are marked as **Enabled** in **Admin** > **Users** and **Organization** > **Users**.
#### Actions
Click the **Update User container** button to migrate a user’s container to the latest image.
Click the **Kill user container** button to restart a user’s container.
Click the **Remove from teams** button to remove a user from all of their assigned groups.
:::info Note
If you change any of the parameters above, click **Save** before leaving the page. Your changes will be applied immediately.
:::
#### Set Password
Here, you can reset a user's login credentials.
If you change this parameter, click **Save** before leaving the page. Your change will be applied immediately.
#### Contact Info
Here, you can change a user’s contact information, including their display name, platform URL, and geographical location.
This information is only visible to platform admins and does not affect a user’s login credentials.
If you change these parameters, click **Save** before leaving the page. Your changes will be applied immediately.
### Setting User Images
In the **Users** tab, select users with their checkboxes. Click **Set Image**.
A dialog box will appear. Enter the **Image Name** and the image **Version**.
Click **Update Image**. Your changes will be applied immediately.
### Updating User Images
In the **Users** tab, select users with their checkboxes. Click **Update in-place**.
A dialog box will appear. Confirm that you’ve selected the users you want to update.
Click **Apply mass-update**. Your changes will be applied immediately.
### Using Impersonate
If you want to quickly access another user's account, you can use the impersonate feature to bypass the login/logout process.
In the **Users** tab, click the impersonate icon for the account you want to access.
You'll be redirected to the user's **Home** page. You can navigate and control resources, storage resources, and workflows as if you were logged in to the user's account.
When you're done, click the user's name, then **Return to [Your Account]**.
## Groups
This tab displays information for all of your groups, including:
- name
- organization
- number of members
- allocation amount
- percentage of allocation used
- state
- creation date
- ID number
All the functions in [**Managing Groups**](/docs/organization-admin/managing-groups) can be completed from this tab as well.
## Instances
This tab displays information for both running instances and other instances, including:
- CSP
- organization that owns the key
- region
- instance ID
- creation date
- instance name, if any
- instance type
- private IP
- public IP
- cloud state
- estimated cloud state time
- ACTIVATE state
Please note that the instance list is wider than most monitors, so the included screenshot does not show all of the fields listed above. To see more information about your instances, scroll to the bottom of the page and use the horizontal scroll bar to show more columns.
You can configure your instance types on the platform by organization. For more information, please see [**Configuring Instance Types**](/docs/organization-admin/cloud/instance-types).
## Workspaces
This tab displays information for all of your user containers, including:
- container name
- user
- container image
- creation date
- type (Docker or Kubernetes)
- safe to kill
### Killing User Containers
In the **Containers** tab, select users with their checkboxes. Click **Kill containers**.
A dialog box will appear. Confirm that you’ve selected the containers you want kill.
Click **Apply mass-update**. Your changes will be applied immediately.
## Images
This tab manages the compute images shown to users when they define clusters. The images listed here are references to images on your cloud service provider (CSP) — deleting an image from this tab will not delete it from the CSP account.
The table groups images by CSP and displays each image's name, ID, region, architecture, and size, along with whether it's **Published** and whether it's the **Latest** image. The `latest` tag automatically points to the most recently added image.
### Adding an Image
Click **Add Machine Image**. On the next page, you can configure the parameters listed below.
- **Name**: the name of the image.
- **CSP**: the cloud service provider the image lives on (**aws**, **google**, **azure**, **openstack**, or **oracle**).
- **CSP ID**: the unique ID of the image in the CSP (e.g., `ami-1234567890` on AWS).
- **Region**: the region the image is in. This field appears for AWS, Oracle, and OpenStack images.
- **Size (GiB)**: the size of the image.
- **Architecture**: **amd64** or **arm64**.
- **OS Type**: the operating system family of the image (**platform**, **rhel**, **ubuntu**, or **windows**).
- **Published**: makes the image available for use.
When you're done, click **Save**. A dialog box with the message _Image added successfully_ will appear.
### Managing Images
Each image's row has a menu with the following actions. Each action asks for confirmation before it's applied.
- **Edit** opens the image's parameters.
- **Set published** and **Set unpublished** control whether the image is available for use. If a published image is currently set as latest, unpublishing it will prevent it from being used as the latest image.
- **Set latest** points the `latest` tag at the image. This action is available for published images only.
- **Disable** and **Enable** control whether the image can be selected by users at all.
- **Delete** permanently removes the image reference from the platform.
## Reports
This tab displays information for your reports, including:
- type of report
- email address that receives reports
- who the report monitors
- frequency
- creator
- creation date
### Creating Reports
In the **Reports** tab, click **+ Add New Report**.
On the next page, you can edit the parameters listed below.
Use the **Type** dropdown menu to select the type of report you want to generate:
- summary
- project
- monthly
- user
- application
Use the **Who** field to enter the username who the report will monitor.
Use the **Email** field to enter the report recipient’s email address.
Use the **Frequency** bubbles to select how frequently the report will be generated:
- daily
- weekly
- monthly
- event (once, at the time of creation)
- test (once, at the time of creation)
- disable (end reports for the time being)
## Webhooks
Webhooks allow external services to be notified when certain events happen. When the specified events happen, we'll send a POST request to each of the URLs you provide.
### Adding a Webhook
Click **+ Add Webhook**.
On the next page, select a **Type**. Currently, you can choose from these webhook types:
- `USER_CREATED` flags when a new user logs in for the first time.
- `USER_DISABLED` flags when a user has been disabled.
- `USER_REMOVED_FROM_GROUP` flags when a user has been removed from a group in your organization.
Add a **Webhook name** and paste the **URL** that your webhook will be sent to. **Description** is an optional field.
Choose whether to **Enable** this webhook.
Click **Create webhook**.
You'll be taken back to the **Webhooks** tab. A dialog box with the message _Webhook created successfully_ will appear in the bottom right corner of your screen.
### Deleting a Webhook
Select the webhook you'd like to delete, then click **Delete webhooks**.
A pop-up module will appear. Click **Delete**.
You'll be taken back to the **Webhooks** tab. A dialog box with the message _Webhook(s) deleted successfully_ will appear in the bottom right corner of your screen.
### Responding to Events
To see the shape of webhooks, please see [this section](/docs/organization-admin/settings/webhooks#responding-to-events). Admin-level webhooks take the same shape as organizaiton-level webhooks, with one exception:
- You will not see `organization` inside the `webhook` object.
## Alerts
This tab collects error messages from all users in your organization. These messages are shown for 7 days before they're automatically deleted.
Use the **Title or message** field to search for alerts by keywords.
Use the **All Dates** dropdown menu to display alerts from a specific date.
Use the **max item** dropdown menu to narrow the listed users to 10, 20, 50, 100, or max items. This option is set to **50** by default.
## Errors
This tab displays recent unknown errors from the platform API, including each error's method, path, message, user, request ID, and time. The oldest entries are automatically removed when the storage limit is reached.
Use the search bar to filter errors by message, path, user, or request ID.
Click **Refresh** to reload the list. You can also click **Trigger Test Error** to generate a sample error and confirm that error reporting is working.
Use the **Previous** and **Next** buttons at the bottom of the page to move through the list.
## Notifications
This tab lets you send notifications to individual users, organizations, or the entire platform. Recipients see them in their [**Inbox**](/docs/your-workspace/inbox).
Use the **Target** dropdown menu to choose who receives the notification:
- **User** sends the notification to a single user. Select the recipient in the **Username** dropdown menu that appears.
- **Organization** sends the notification to every user in an organization. Select the recipient in the **Organization** dropdown menu that appears.
- **All** sends the notification to every user on the platform.
Use the **Level** dropdown menu to select **Info** or **Alert**.
Enter a **Notification title**. You can optionally add a **Message** and a **Notification href**, which attaches a link to the notification.
The **Preview** section shows what the notification will look like to recipients. When you're ready, click **Send notification**. A dialog box with the message _Notification sent successfully_ will appear.
## Previews
This tab manages platform-wide feature previews. When a preview is enabled here, it's active for all users and cannot be individually disabled.
Click a feature card to see its details, including which users have enabled it under **Enabled by Users**. Features marked **Admin only** aren't visible to regular users.
If previews that no longer exist on the platform are still present in user accounts, an _Orphaned previews_ message will appear. Click **Clean up** to remove them.
## Integrations
This tab connects third-party services to extend platform functionality. Each integration card shows whether the service is **Configured** or **Not configured**.
#### Sentry
The Sentry integration monitors errors, performance, and user sessions. Click **Configure** to set it up. Once configured, error tracking and session replays are active.
#### Health Monitoring
The Health Monitoring integration shares a small health snapshot with Parallel Works every 5 minutes so support can catch expiring certificates, failed certificate renewals, and outages before they cause downtime. Reporting is **on by default**; click **Edit** on its card to review exactly what is sent or to turn it off.
Each snapshot contains only the following. It never includes usernames, email addresses, IP addresses, job or workflow data, or any other user content.
| Field | Contents |
| --- | --- |
| Version | The deployment's installed platform version |
| Domains | Per platform domain: domain name, certificate expiry date, certificate source, and renewal status |
| License | License expiry date and whether it is in the grace period or expired |
| Health | Whether the deployment can reach its own database, and the process start time |
| Usage | Monthly active user count, assigned seat count, and total/free seat counts when seat allocations are configured |
Snapshots are pushed over outbound HTTPS; nothing connects back into the deployment, and a failed send is simply retried at the next interval without affecting the deployment itself. The identity the deployment reports as (shown on the tile under **Reports as**) is derived from its platform license.
To stop reporting, toggle **Enable reporting** off and save. The change takes effect within one interval, without a restart. You can also point **Custom endpoint** at your own receiver instead of the Parallel Works default.
#### GitHub
The GitHub integration connects a GitHub App to enable repository access on the platform. Click **Configure** to set it up. Once configured, users can link their GitHub accounts in their account settings. For more information, please see [**Connections**](/docs/account-settings/connections).
To remove the GitHub App configuration, click the delete icon on its card.
:::warning Irreversible Action
Removing the GitHub App configuration will disconnect all linked users and delete all stored credentials.
:::
## PKI Validation
This tab serves a configurable token file at `/.well-known/pki-validation/` for HTTP-based domain control validation, which some certificate issuers require when provisioning SSL/TLS certificates.
:::info Note
The file is served over plain HTTP without authentication.
:::
Enter the **Filename**, including its extension (e.g., `1e2175b230684937b0093e71b3cc3404.txt`), and paste the verification token in the **File contents** field. The file body is preserved exactly, including whitespace.
Once you enter a filename, the **Public URL** field displays the address where the file will be served. Click **Save** to start serving the file. The tab will display an **Active** badge while a file is being served.
To stop serving the file, click **Remove**. A dialog box will appear; click **Remove** to confirm. The endpoint will return a 404 error afterward.
## Migrations
This tab runs and manages database migrations for Postgres and MongoDB. It's primarily used when operating a [self-hosted ACTIVATE deployment](/docs/self-hosting/kubernetes-deployment).
The **Mongo Migrations Registry** table lists each migration with its status (**Applied** or **Not Applied**), whether it runs automatically, when it was first applied, and who applied it. Click **Run** (or **Rerun**) in a migration's row to execute it individually, or click **Run Unapplied Auto Mongo Migrations** to run all pending automatic migrations.
To run migrations in bulk, click **Run Migrations** and choose **Both (Postgres + Mongo)**, **Postgres Only**, or **Mongo Only**.
:::warning Irreversible Action
Running migrations will modify your database schema and data. Ensure you have backups before proceeding.
:::
The **Migration Run History** section logs each run with its start time, duration, actor, and per-step results. Click **Delete All Logs** to clear the history. Deleting logs only removes the log entries; it does not affect the migrations or the data in your database.
## Maintenance
This tab cleans up old or orphaned data to free database space and keep the platform running smoothly.
Each operation shows a preview of what will be deleted before you confirm.
:::warning Irreversible Action
Deletions on this tab permanently remove data from the database and cannot be undone.
:::
#### Old Workflow Runs Cleanup
This section removes workflow runs created before a specified time period. Enter a number of months in the **Delete workflow runs older than** field and click **Preview** to see how many runs will be deleted. If the preview returns results, click **Delete Workflow Runs** and confirm.
#### Orphaned Workflow Runs
This section finds workflow runs that reference non-existent users or workflows — for example, runs where the user has been deleted, or where the workflow definition no longer exists. Click **Scan for Orphaned Runs** to preview them, then click **Delete Orphaned Runs** and confirm.
#### Orphaned Infrastructures
This section finds infrastructure that references non-existent users — resources whose owner's account has been deleted. Click **Scan for Orphaned Infra** to preview them, then click **Delete Orphaned Infra** and confirm.
# Platform Policies
> Source: https://parallelworks.com/docs/admin-panel/policies
# Platform Policies
## Navigation
In the **Admin Panel** sidebar, under **Configuration**, click **Policies**.
## Overview
Platform policies are enforced across all organizations. When a platform policy is set, it takes precedence over the corresponding [organization policy](/docs/organization-admin/settings/policies) and cannot be overridden by organization admins. When **No policy** is selected, each organization can choose whether to apply the policy for itself.
## Policies
### No Root Access
Disable root access to cloud compute resources for all users, including resource owners, across all organizations. Defaults to "Enable root access" if no policy is set.
### Nitro Instance Types Only
Restrict compute resources to AWS Nitro instance types only, across all organizations. Defaults to "Allow all AWS instance types" if no policy is set.
### No Public IP Addresses
Prevent users from provisioning standalone public IP addresses, across all organizations. Defaults to "Allow public IP addresses" if no policy is set.
When enabled, requests to provision a standalone public IP address are rejected.
### Archive Cost Data
Automatically summarize and then archive cost data after a specified number of months to optimize database performance. This will not delete any data, it will only summarize older data.
Cost data can be archived after 1, 3, 6, or 12 months.
### Enforce Security Key MFA
:::note Feature Preview
This policy is feature-flagged and may not be visible on your platform.
:::
Require all users to set up and use a hardware security key (such as a YubiKey) for multi-factor authentication when logging in with a password. Users without a registered security key will be prompted to register one before accessing the platform.
Users signing in through an OpenID Connect provider with **Skip Platform MFA Verification** enabled are not affected by this policy; their identity provider is trusted to perform multi-factor authentication.
# AI
> Source: https://parallelworks.com/docs/ai
# AI
ACTIVATE AI brings your organization's AI usage under one governed gateway. Connect your own AI providers — hosted services or models running on your own infrastructure — and ACTIVATE manages access to them through a built-in chat workspace, API keys, and token-level usage tracking.
## Chat
Chat is a full-featured chat interface for interacting with large language models directly within the platform. You can have conversations with AI models, attach files for context, branch conversations to explore different approaches, and share conversations with teammates.
- [Chat Overview](/docs/ai/chat) — Get started with the chat interface, learn about available features
## pw code
`pw code` is an AI coding agent that runs in your terminal. It reads and edits files, runs commands, and works through multi-step tasks, with sessions stored locally on your machine. See [pw code](/docs/ai/code) for install, quick start, and features.
## The AI Gateway
The AI gateway is how ACTIVATE manages access to your providers. Every request — whether it comes from Chat, [the CLI](/docs/ai/code), or an external tool authenticating with an AI key — is proxied through the platform, where access is checked and token usage is metered against your organization's budget allocations.
- [AI Providers](/docs/ai/ai-providers) — Connect the model backends that power the gateway
- [AI Keys](/docs/ai/ai-keys) — Create API keys for programmatic access through the OpenAI-compatible API
- [AI Usage](/docs/ai/ai-usage) — Track spend, tokens, and budget allocations
- [Best Practices](/docs/ai/best-practices) — Tips for prompting, model selection, and security
## Related Documentation
- [Machine Learning](/docs/ml) — ML workspace resources
- [Getting Started](/docs/getting-started) — Tutorial for new users
# AI Keys
> Source: https://parallelworks.com/docs/ai/ai-keys
# AI Keys
AI keys let external tools and applications authenticate to your organization's [AI providers](/docs/ai/ai-providers/) through the ACTIVATE AI gateway. Requests made with a key are proxied through the platform, where token usage is metered and billed — so programmatic access carries the same governance as the rest of ACTIVATE.
Each key is bound to a budget allocation when it is created. Usage made with the key draws from that allocation, and once the allocation's budget is exhausted, further requests are rejected with a payment-required error before they reach a model. Usage made with a key is tracked on the [AI Usage](/docs/ai/ai-usage) dashboard, where it can be broken down per key.
## Managing Keys {#ai-api-keys}
AI keys belong to your user account — each user creates and manages their own keys. To manage your keys, navigate to **AI** > **AI Keys** in the sidebar.
The page lists each key with its creation date, expiration date, when it was last used, and its allocation, if any. Use the **Filter keys** field to search the list.
Click **Create key** to add a new key.
:::info Note
Keys are shown once at creation. Store them in a password manager — once you navigate away, you won't be able to see the key again.
:::
To revoke a key, click the delete icon in its row.
## Using a Key with the OpenAI-Compatible API
The gateway exposes an OpenAI-compatible API, so existing SDKs and tools work when pointed at ACTIVATE instead of directly at a vendor. Send requests to the chat completions endpoint at `/api/openai/v1/chat/completions`, authenticating with an AI key. Model IDs use the format `owner:provider-name/model-name`.
For step-by-step setup guides for tools like Open WebUI, OpenCode, Kilo Code, and Cursor, see [Connect External Tools](/docs/ai/ai-providers/connect/).
## Related Documentation
- [AI Providers](/docs/ai/ai-providers/) — Connect the model backends behind the gateway
- [AI Usage](/docs/ai/ai-usage) — Track spend, tokens, and budget allocations
- [Chat](/docs/ai/chat/) — Using the chat interface
# AI Providers
> Source: https://parallelworks.com/docs/ai/ai-providers
# AI Providers
AI providers are the model backends behind the ACTIVATE AI gateway. Each provider connects the platform to a large language model endpoint, powering both [Chat](/docs/ai/chat/) and programmatic access through [AI keys](/docs/ai/ai-keys/).
ACTIVATE supports three types of providers:
- **Azure OpenAI** — A managed provider provisioned through your organization's Azure infrastructure. ACTIVATE handles deployment and configuration automatically.
- **Custom OpenAI-Compatible** — Any endpoint that implements the OpenAI chat completions API. Use this to connect services like vLLM, Ollama, or other compatible inference servers.
- **Session Tunnels** — A secure tunnel from the platform to a model running inside an ACTIVATE compute session. Useful for private or fine-tuned models running on your own hardware.
:::info Permissions Required
Creating and managing AI providers requires appropriate platform permissions. In most organizations, providers are set up by administrators or team leads and then shared with other users.
:::
## Provider Permissions
Each provider has its own access controls. The provider owner and organization administrators can share a provider with specific groups or the entire organization using the `aiprovider:use` permission. Users who have been granted access can select the shared provider in Chat.
See [Managing Permissions](/docs/ai/ai-providers/managing-permissions) for details on sharing and revoking access.
## AI Keys
Users can create **AI keys**, which let external tools and applications authenticate to the organization's AI providers through the gateway. Each key belongs to the user who created it and draws from a budget allocation. See [AI Keys](/docs/ai/ai-keys/) for creating keys and using the OpenAI-compatible API.
## Next Steps
- [Azure OpenAI](/docs/ai/ai-providers/azure-openai) — Set up a managed Azure OpenAI provider
- [Custom OpenAI-Compatible](/docs/ai/ai-providers/custom-openai-compatible) — Connect any OpenAI-compatible endpoint
- [Session Tunnels](/docs/ai/ai-providers/session-tunnels) — Route chat through a model in a compute session
- [Managing Permissions](/docs/ai/ai-providers/managing-permissions) — Control who can use your providers
- [Connect External Tools](/docs/ai/ai-providers/connect) — Use your models from editors and other OpenAI-compatible tools
- [Tool Calling & Emulation](/docs/ai/ai-providers/tool-calling) — How agentic tool calling works, including on endpoints without a tools API
## Related Documentation
- [Chat](/docs/ai/chat/) — Using the chat interface
- [AI Keys](/docs/ai/ai-keys/) — Programmatic access through the gateway
- [Adding an ML Resource](/docs/ml/adding-ml-resources/) — Provisioning ML workspaces
# Azure OpenAI Provider
> Source: https://parallelworks.com/docs/ai/ai-providers/azure-openai
# Azure OpenAI Provider
The Azure OpenAI provider is a managed integration that provisions an Azure OpenAI deployment through your organization's cloud infrastructure. ACTIVATE handles the deployment lifecycle, so you do not need to manually configure Azure resources.
## Prerequisites
Before creating an Azure OpenAI provider, ensure that:
- Your organization has at least one **provisioned network** in ACTIVATE
- You have a **billing group** associated with your account
- Your organization's Azure subscription supports Azure OpenAI deployments in your target region
## Creating a Provider
1. Navigate to **AI** > **Providers** in the ACTIVATE sidebar.
2. Click **Add Provider**.
3. Select **Azure** as the cloud service provider.
4. Fill in the required fields:
- **Name** — A descriptive name for the provider (for example, "Azure GPT-4o").
- **Network** — Select the provisioned network to deploy with.
- **Group** — Select the billing group to associate with this provider.
- **Region** — The Azure region for the deployment (for example, "eastus2").
- **Model** — The model to deploy (for example, "gpt-4o").
5. Optionally add a **Description** and **Tags**.
6. Click **Create**.
The provider will enter a **provisioning** status while ACTIVATE configures the Azure resources. Once provisioning completes, the status changes to **provisioned** and the provider is ready to use in Chat.
## Verifying the Provider
After provisioning completes:
1. Open **Chat**.
2. Select your new Azure provider from the provider dropdown.
3. Send a test message to confirm the model responds.
If the provider does not appear in the dropdown, verify that your user account has access. See [Managing Permissions](/docs/ai/ai-providers/managing-permissions) for details.
## Updating a Provider
Azure providers are managed by the platform. The model and deployment configuration are set during provisioning. To change the model or region, delete the existing provider and create a new one.
## Deleting a Provider
1. Navigate to **AI** > **Providers**.
2. Find the provider you want to remove.
3. Click the delete action for that provider.
4. Confirm the deletion.
Deleting an Azure provider tears down the associated Azure resources. This action cannot be undone.
## Related Documentation
- [AI Providers Overview](/docs/ai/ai-providers) — Overview of all provider types
- [Managing Permissions](/docs/ai/ai-providers/managing-permissions) — Sharing providers with your team
- [Custom OpenAI-Compatible](/docs/ai/ai-providers/custom-openai-compatible) — Connecting non-Azure endpoints
# Connect External Tools
> Source: https://parallelworks.com/docs/ai/ai-providers/connect
# Connect External Tools
Use your platform AI models with external tools and editors. Any tool that supports an OpenAI-compatible provider can send requests through the ACTIVATE AI gateway, authenticated with an [AI key](/docs/ai/ai-keys/) and governed by the same budgets and usage tracking as the rest of the platform.
To open the page, navigate to **AI** > **Providers** in the sidebar and click **Connect Tools**.
## Base URL and API Key
External tools need two values, both available at the top of the page:
- **Base URL** — your organization's gateway endpoint, `https:///api/openai/v1`. Click the URL on the page to copy it with your actual domain filled in.
- **AI API Key** — click **Create Key** to generate a key without leaving the page. Keys are shown once at creation; see [AI Keys](/docs/ai/ai-keys/) for managing them.
## Available Models
The **Your models** list shows every model you can access across your providers — click a model to copy its ID. Model IDs use the format `owner:provider-name/model-name`. If the list is empty, add or get access to a provider first; see [AI Providers](/docs/ai/ai-providers/).
## Setup Guides
The page includes step-by-step guides for popular tools. Each guide inserts your Base URL, API key, and model IDs in place.
### Open WebUI
A self-hosted, feature-rich web interface for AI chat.
1. Open your Open WebUI instance, click your avatar in the bottom-left corner, and select "Admin Panel".
2. Go to the Settings tab, then navigate to Connections > OpenAI.
3. Click the "+" button to add a new connection.
4. Enter your Base URL.
5. Paste your API key into the Auth field (leave the type set to "Bearer").
6. Click "Save" to add the connection.
### OpenCode
An AI coding assistant with OpenAI-compatible provider support.
**Desktop**
1. Open OpenCode and go to Settings > Providers.
2. Scroll down to "Custom provider" and click "+ Connect".
3. Enter a Provider ID (e.g. "pw") and a Display name (e.g. "Parallel Works").
4. Set the Base URL to your gateway Base URL.
5. Paste your API key into the API key field.
6. Under Models, enter one of your model IDs and a display name, then click "Submit". Repeat to add more.
**CLI**
1. Launch OpenCode in your terminal and run the `/connect` command to register a new provider credential.
2. Enter a Provider ID (e.g. "pw") and select "Other" when prompted for a provider.
3. Paste your API key when OpenCode prompts for it.
4. Open (or create) `opencode.json` in your project root or at `~/.config/opencode/opencode.json`, then add this provider entry:
```json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"pw": {
"npm": "@ai-sdk/openai-compatible",
"name": "Parallel Works",
"options": {
"baseURL": "https:///api/openai/v1"
},
"models": {
"model-id-here": {
"name": "Model Display Name"
}
}
}
}
}
```
5. Replace `model-id-here` with one of your model IDs. Add more entries under `models` for every model you want available.
6. Restart OpenCode. Your custom provider and models will appear in the model picker.
:::info Tip
OpenCode Desktop and CLI share the same `opencode.json`. If you already set up the desktop variant above, the CLI will pick up the same provider. The quickest path is often to configure in the desktop and then just run `opencode` in your terminal.
:::
### Kilo Code
An open-source AI coding assistant for VS Code with OpenAI-compatible provider support.
1. Open VS Code and install the Kilo Code extension.
2. Open the Kilo Code panel, open Settings, and choose Providers.
3. Click "Connect" next to "Custom provider".
4. Enter a Provider ID (e.g. "pw") and a Display name (e.g. "Parallel Works").
5. Set the Base URL to your gateway Base URL.
6. Paste your API key into the API key field.
7. Kilo Code fetches your available models automatically. Select the ones you want and click "Add N model(s)".
### Cursor
An AI-powered code editor built on VS Code with integrated chat and code generation.
1. Open Cursor and go to Settings > Models.
2. Expand the "API Keys" section and enable the "OpenAI API Key" toggle.
3. Paste your API key into the OpenAI API Key field.
4. Enable the "Override OpenAI Base URL" toggle and set it to your gateway Base URL.
5. Scroll down and click "+ Add Custom Model", enter one of your model IDs, and click "Add". Repeat for every model you want available.
6. Turn off "Auto" mode in the model picker. Otherwise Cursor ignores your custom models and routes to its own.
## Related Documentation
- [AI Keys](/docs/ai/ai-keys/) — Creating and managing keys
- [AI Providers](/docs/ai/ai-providers/) — Connecting model backends
- [AI Usage](/docs/ai/ai-usage/) — Tracking spend from external tools
# Custom OpenAI-Compatible Provider
> Source: https://parallelworks.com/docs/ai/ai-providers/custom-openai-compatible
A custom provider connects ACTIVATE to any endpoint that implements the OpenAI chat completions API. This gives you flexibility to use self-hosted models, third-party inference services, or any other compatible backend.
## Endpoint Requirements
Your endpoint must support the following:
- **POST `/v1/chat/completions`** — The standard OpenAI chat completions endpoint. ACTIVATE sends all chat messages to this route.
- **GET `/v1/models`** (optional) — If your endpoint exposes this route, ACTIVATE can list available models dynamically so users can switch models without reconfiguring the provider.
The endpoint must accept an API key via the `Authorization: Bearer ` header.
## Prerequisites
Before creating a custom provider, ensure that:
- Your inference endpoint is running and reachable from the ACTIVATE platform
- You have the endpoint URL and a valid API key
## Creating a Provider
1. Navigate to **AI** > **Providers** in the ACTIVATE sidebar.
2. Click **Add Provider**.
3. Select **Custom** as the cloud service provider.
4. Fill in the required fields:
- **Name** — A descriptive name for the provider (for example, "vLLM Llama 3").
- **Endpoint** — The full URL to your chat completions endpoint (for example, `https://my-server.example.com/v1/chat/completions`).
- **API Key** — The authentication key for your endpoint.
5. Optionally add a **Description** and **Tags**.
6. Click **Create**.
Custom providers are available immediately after creation — no provisioning step is required.
## Verifying the Provider
1. Open **Chat**.
2. Select your new custom provider from the provider dropdown.
3. Send a test message to confirm the endpoint responds correctly.
ACTIVATE automatically discovers available models by querying your endpoint's `/v1/models` route. If the model list dropdown is populated, your endpoint supports this route and ACTIVATE has successfully queried it.
## Updating a Provider
You can update the endpoint and API key for a custom provider at any time:
1. Navigate to **AI** > **Providers**.
2. Select the provider you want to update.
3. Modify the fields as needed.
4. Save your changes.
This is useful for rotating API keys or pointing the provider at a different endpoint without creating a new provider.
## Notes for Common Inference Servers
**vLLM** — Start vLLM with the `--api-key` flag to enable API key authentication. The default port is 8000. Your endpoint URL will be `http://:8000/v1/chat/completions`.
**Ollama** — Ollama exposes an OpenAI-compatible API on port 11434. Set the endpoint to `http://:11434/v1/chat/completions`. The model name should match the Ollama model tag (for example, "llama3").
**Text Generation Inference (TGI)** — TGI provides an OpenAI-compatible Messages API. Set the endpoint to `http://:8080/v1/chat/completions`.
## Exposing a Local Server Through an Endpoint
To expose a server on a machine you control, use an [endpoint session](/docs/run/sessions/endpoints/#expose-a-local-ai-model): `pw endpoints http --openai ` registers it as a model automatically, or drop `--openai` and use the endpoint's public URL as the **Endpoint** above. A server that rejects the forwarded `Host` (such as Ollama) also needs [`--rewrite-host`](/docs/run/sessions/endpoints/#a-local-app-rejects-the-tunneled-request).
## Deleting a Provider
1. Navigate to **AI** > **Providers**.
2. Find the provider you want to remove.
3. Click the delete action for that provider.
4. Confirm the deletion.
Deleting a custom provider only removes it from ACTIVATE. It does not affect the external inference endpoint.
## Related Documentation
- [AI Providers Overview](/docs/ai/ai-providers) — Overview of all provider types
- [Managing Permissions](/docs/ai/ai-providers/managing-permissions) — Sharing providers with your team
- [Session Tunnels](/docs/ai/ai-providers/session-tunnels) — Tunneling to a model running in a compute session
# Managing Provider Permissions
> Source: https://parallelworks.com/docs/ai/ai-providers/managing-permissions
# Managing Provider Permissions
AI providers support a permission system that lets you control who can use your providers. By default, a provider is private to its owner. You can share it with specific groups or your entire organization.
## Permission Model
ACTIVATE uses the `aiprovider:use` permission to control access to AI providers. This is the only permission level for providers — granting it allows the recipient to select the provider in Chat and send messages through it.
Access to a provider is determined by the following rules, evaluated in order:
1. **Owner** — The user who created the provider always has full access, including the ability to manage permissions.
2. **Organization administrators** — Org admins can access and manage permissions for any provider in the organization.
3. **Granted permissions** — Users who belong to a group that has been granted `aiprovider:use` on the provider, or users in an organization where the provider is shared organization-wide.
## Who Can Manage Permissions
Only the provider **owner** and **organization administrators** can view or modify provider permissions. Other users with `aiprovider:use` access can use the provider but cannot change its sharing settings.
## Sharing a Provider with a Group
1. Navigate to **AI** > **Providers**.
2. Select the provider you want to share.
3. Open the **Permissions** settings for the provider.
4. Under **Groups**, find the group you want to share with.
5. Enable the `aiprovider:use` permission for that group.
6. Save your changes.
All members of the selected group will now see the provider in their provider list in Chat.
## Sharing a Provider with the Entire Organization
1. Navigate to **AI** > **Providers**.
2. Select the provider you want to share.
3. Open the **Permissions** settings for the provider.
4. Under **Organization**, enable the `aiprovider:use` permission.
5. Save your changes.
Every user in your organization will now have access to this provider.
## Revoking Access
To remove access for a group or the organization:
1. Open the **Permissions** settings for the provider.
2. Disable the `aiprovider:use` permission for the group or organization.
3. Save your changes.
Users who lose access will no longer see the provider in their provider list in Chat. Existing conversations that used the provider will remain, but users will not be able to send new messages through it.
## Best Practices
- **Start with group-level sharing.** Share providers with specific teams that need them rather than the entire organization. This limits unnecessary usage and cost.
- **Use descriptive provider names.** When sharing across groups, a clear name like "Azure GPT-4o (East US)" helps users identify the right provider.
- **Audit permissions periodically.** Review which groups have access to each provider, especially for providers connected to paid endpoints.
- **Rotate API keys regularly.** For custom providers, update the API key in the provider settings when you rotate credentials on the backend.
:::info Session Tunnels
Session tunnel providers do not support the permissions system. They are private to the user who created the tunnel.
:::
## Related Documentation
- [AI Providers Overview](/docs/ai/ai-providers) — Overview of all provider types
- [Azure OpenAI](/docs/ai/ai-providers/azure-openai) — Setting up managed Azure providers
- [Custom OpenAI-Compatible](/docs/ai/ai-providers/custom-openai-compatible) — Connecting external endpoints
# Session Tunnel Providers
> Source: https://parallelworks.com/docs/ai/ai-providers/session-tunnels
# Session Tunnel Providers
A session tunnel provider routes Chat traffic through a secure tunnel to a model running inside an ACTIVATE compute session. This allows you to use models hosted on your own cluster hardware without exposing them to the public internet.
## How Session Tunnels Work
When you start a session in ACTIVATE with an OpenAI-compatible model server running on it, you can create a tunnel that makes the model available to Chat. The tunnel establishes a secure connection between the ACTIVATE platform and the model endpoint inside your session.
Session tunnel providers appear in the provider list in Chat with the type `openai-tunnel`. They are automatically discovered when a tunnel with the OpenAI flag enabled is active for your user account.
## Prerequisites
Before using a session tunnel provider:
- You have an active ACTIVATE session running on a cluster
- An OpenAI-compatible model server is running inside the session (for example, vLLM, Ollama, or TGI)
- A tunnel has been created from the session with the **OpenAI** option enabled
## Setting Up a Session Tunnel
1. Start a **session** on your cluster with enough resources to run your model (GPU, memory).
2. Inside the session, start an OpenAI-compatible inference server on a known port.
3. Create a **tunnel** for that session and enable the **OpenAI** toggle.
4. Once the tunnel status shows as **running**, the provider appears automatically in your provider list in Chat.
You do not need to manually create a provider entry. ACTIVATE detects tunnels with the OpenAI flag and includes them in your available providers.
## Using a Session Tunnel Provider
1. Open **Chat**.
2. In the provider dropdown, look for your tunnel. It will show with the status of the tunnel (for example, "running" or "stopped").
3. Select the tunnel provider and send a message.
If the tunnel is in a "stopped" state, you must restart the session and tunnel before it can serve requests.
## Use Cases
- **Air-gapped environments** — Run models on infrastructure that has no direct internet access. The tunnel provides a secure path from ACTIVATE to the model.
- **Sensitive data** — Keep model inference on your own hardware to ensure data does not leave your environment.
- **Custom fine-tuned models** — Serve models you have fine-tuned on proprietary data without uploading them to a cloud provider.
- **Experimentation** — Quickly test different models by starting sessions with different configurations.
## Limitations
- **Session dependency** — The tunnel provider is only available while the session and tunnel are active. If the session stops, the provider becomes unavailable.
- **No sharing** — Session tunnel providers are tied to the user who created the tunnel. They cannot be shared with other users via the permissions system.
- **Single user** — Each tunnel is associated with one user account.
## Related Documentation
- [AI Providers Overview](/docs/ai/ai-providers) — Overview of all provider types
- [Custom OpenAI-Compatible](/docs/ai/ai-providers/custom-openai-compatible) — Connecting a persistent external endpoint
- [Sessions](/docs/run/sessions) — Managing compute sessions
# Tool Calling & Emulation
> Source: https://parallelworks.com/docs/ai/ai-providers/tool-calling
# Tool Calling & Emulation
Agentic clients such as [`pw code`](/docs/ai/code/) work by calling tools: the model asks to read a file, run a command, or search the workspace, and the client executes the request and returns the result. Many model endpoints implement tool calling directly, but some do not.
Every model reachable through the ACTIVATE AI gateway is advertised with one of three tool-calling modes. Models whose endpoint has no tool-calling API can still be used for agentic work through **emulated tool calling**, which the gateway handles on their behalf.
## The Three Modes
| Mode | Meaning |
| --- | --- |
| `native` | The provider's endpoint implements tool calling. The gateway passes tool definitions and tool calls straight through. |
| `emulated` | The provider's endpoint has no tool-calling API. The gateway carries the tool contract in the prompt and reconstructs tool calls from the model's text. |
| `none` | Tool calling is unavailable for this provider. Requests that carry tool definitions are rejected. |
The mode is a property of the provider integration, not of the individual model. Platform administrators set it when creating or editing a provider, and it is required when registering a custom OpenAI-compatible integration. Built-in integrations ship with the correct mode already set; GenAI.mil, for example, is registered as `emulated`.
### Seeing the Mode
The mode is reported wherever models are listed:
```bash
# The "Tool calling" column shows yes, emulated, or no
pw ai models ls
```
The models endpoint returns it as `tool_calling_mode` on each entry:
```bash
GET /api/openai/v1/models
```
Inside an interactive `pw code` session, the status line below the composer shows `emulated tools` when the active model is running in emulated mode, and `tools unavailable` when the model's mode is `none`.
## Why Emulation Exists
Some endpoints, including agent-wrapper services and a number of self-hosted inference servers, accept OpenAI-compatible chat requests but do not support the `tools` parameter. Without emulation, those models would be limited to chat and could not be used with `pw code`.
Emulation makes tool calling a property of the gateway rather than of the provider. Clients send the same OpenAI-shaped request with a `tools` array and receive the same `tool_calls` in the response, so no client-side configuration changes.
## Architecture
All three modes follow one path from the client to the model. The gateway resolves the provider, reads its tool-calling mode, and applies the matching translation layer. Only the emulation layer rewrites the request; native passes it through and `none` rejects it.
or any OpenAI-compatible client"]
subgraph gateway["ACTIVATE AI gateway"]
resolve["Reads the provider's tool calling mode"]
native["Native pass tools through"]
emulate["Emulated tool contract in the prompt"]
none["None tool calls rejected"]
end
subgraph providers["Model endpoints"]
withtools["Endpoint with a tools API"]
notools["Endpoint without a tools API"]
end
client -->|"request with tools"| resolve
resolve --> native
resolve --> emulate
resolve --> none
native <--> withtools
emulate <-->|"plain chat"| notools
emulate -.->|"tool calls"| client
native -.->|"tool calls"| client
classDef gatewayNode fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f
classDef emulateNode fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#78350f
classDef providerNode fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#064e3b
classDef clientNode fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#4c1d95
class resolve,native,none gatewayNode
class emulate emulateNode
class withtools,notools providerNode
class client clientNode
style gateway stroke:#3b82f6,stroke-width:2px
style providers stroke:#10b981,stroke-width:2px
`} />
The client uses the same contract in every mode. It sends `tools`, receives `tool_calls`, and runs them locally in your workspace. The model does not execute anything itself in either mode.
## How Emulation Works
When a request with tool definitions is routed to an emulated provider, the gateway translates in both directions. A single tool round trip looks like this.
>G: request with tool definitions
Note over G: Move the tool contract into the prompt Add a per-request nonce
G->>M: plain chat request
M-->>G: JSON envelope as text
Note over G: Check the framing values Validate the arguments
G-->>C: standard tool calls
Note over C: Run the tool in the workspace
C->>G: tool result
Note over G: Fence the result as untrusted data
G->>M: chat request with the result
M-->>G: plain text answer
G-->>C: assistant message
`} />
### 1. The Tool Contract Moves Into the Prompt
The gateway strips `tools`, `tool_choice`, and `parallel_tool_calls` from the upstream request and appends an instruction block to the conversation describing:
- The full JSON Schema of every tool the client defined.
- The exact shape of a tool-call **envelope** the model must emit.
- The tool policy for this request, derived from `tool_choice` (optional, required, or one named function) and from whether parallel calls are allowed.
The block is appended to the **user turn** rather than sent as a system message. Some agent-wrapper endpoints apply their own system prompt and discard the one supplied by the caller, while still honoring user content, so instructions sent as a system message would not reach the model on those providers.
### 2. The Model Replies With an Envelope
To call a tool, the model responds with a single JSON object and nothing else:
```json
{
"protocol": "parallelworks.tool-call.v1",
"toolset": "sha256:9f2c…",
"nonce": "4b81f0c39ad2",
"calls": [
{ "name": "Bash", "arguments": { "command": "ls -la", "description": "list files" } }
]
}
```
The gateway checks three framing values before it honors an envelope:
- **`protocol`** identifies the envelope format.
- **`toolset`** is a digest of the tool definitions sent with this request, so an envelope written against a different set of tools is not accepted.
- **`nonce`** is generated for each request and must be echoed back. Content that existed before the request cannot contain the current nonce, so an envelope taken from earlier conversation content or from tool output is not accepted as a live call.
### 3. The Gateway Validates and Converts
The gateway locates the envelope in the model's output, allowing for code fences and surrounding prose, then checks it:
- Protocol, toolset, and nonce must match this request.
- The named tool must be one the client defined.
- The arguments must validate against that tool's JSON Schema.
- The call count must match the request's parallel-call policy.
A valid envelope becomes ordinary OpenAI `tool_calls` with generated call IDs and a `tool_calls` finish reason, so the client receives a standard tool-calling response.
Output that is not an envelope attempt is returned unchanged as a plain text answer. Ordinary replies, including replies that contain JSON, are not affected.
### 4. Near Misses Are Repaired, Then Retried Once
Models trained on other tool formats produce a small set of predictable variations. The gateway repairs these locally rather than making another upstream call:
- Alternate field names for the call list (`tool_calls`, `toolCalls`) and for arguments (`parameters`, `args`, `input`).
- A call wrapped in a `function` / `function_call` object.
- A single call emitted bare, or a call list emitted as one object instead of an array.
- Arguments emitted as a JSON string instead of an object.
- Extra top-level fields, duplicate keys, and reordered or reserialized JSON.
Repairs are re-validated against the same rules, and a repaired envelope that still fails validation is not accepted. Nonce repair is declined when the envelope appears to have been copied out of tool output.
If validation still fails, the gateway makes one corrective retry. It replays the rejected output, states the reason it was rejected, and supplies a skeleton envelope with the correct protocol, toolset, and nonce already filled in, leaving the model only the call to write. If the retry also fails, the request returns an error rather than passing malformed text back as an answer.
### 5. Tool Results Go Back as Fenced, Untrusted Data
On the next turn, the client's `tool` messages are rendered as text the model can read. Each result is wrapped in `[TOOL_OUTPUT ]` markers carrying the same per-request nonce and labeled as untrusted data that must not be followed as instructions. Since the nonce is new for each request, earlier output cannot reproduce the markers to close the fence early or imitate gateway framing. Images in tool results are passed through as images.
## Behavior to Expect
**Streaming.** A streaming request to an emulated model is still streamed from the provider, but the gateway needs the complete response before it can tell whether the output is an envelope or an answer. The response is buffered and then sent to the client as a stream, so tokens do not appear incrementally as they do with a native provider.
**Prompt caching.** The tool contract sits in the user turn and carries a per-request nonce, so the prompt prefix differs on every request. Emulated requests do not benefit from provider-side prompt-prefix caching.
**Token cost.** Each request repeats the JSON Schema of every tool in the prompt, which accounts for a noticeable share of input tokens when the toolset is large. A corrective retry adds the cost of a second call for that turn. Usage from both calls is metered.
**The Responses API.** Emulation is available over Chat Completions only. A request to `/api/openai/v1/responses` for an emulated provider is rejected with `tool_call_emulation_requires_chat_completions`, and the models list advertises emulated integrations as Chat Completions.
**Reliability.** Emulation depends on the model following instructions and copying the framing values accurately. Models that follow instructions well use tools consistently; smaller models, and models behind an agent wrapper, call tools less consistently than they would through a native API.
## Limits
Requests that exceed these bounds are rejected before they are sent upstream.
| Limit | Value |
| --- | --- |
| Tools per request | 128 |
| Calls per envelope | 32 |
| Encoded tool definitions | 2 MB |
| Envelope size | 2 MB |
| JSON nesting depth (tools and envelope) | 64 |
| Buffered response size | 16 MB |
Tool names must be 1 to 64 characters of letters, numbers, underscores, or hyphens, and must be unique within a request. Only function tools are supported. Parameter schemas that expand to a very large number of branches through `$ref` and `anyOf` are rejected before compilation.
## Troubleshooting
**The status line says `emulated tools` unexpectedly.** The active model's provider is registered as `emulated`. Switch to a model from a `native` provider with `/model`, or ask an administrator whether the provider's mode is correct for its endpoint.
**The model answers in prose instead of using a tool.** This is the most common emulation failure. Stating the action directly ("read `main.go` and tell me what it does") usually helps, as does selecting a larger model from the same provider.
**"This model does not support tool calling."** The provider is registered as `none`. Run `pw code --no-tools` for a chat-only session, or choose a different model.
**Calls fail repeatedly on one specific tool.** Emulated arguments are validated against the tool's JSON Schema as written. A large or deeply nested schema is harder for a model to satisfy from a prompt than through a native API, so simplifying the schema usually resolves it.
## Related Documentation
- [Custom OpenAI-Compatible](/docs/ai/ai-providers/tool-calling/custom-openai-compatible) — Register an endpoint and set its tool-calling mode
- [pw code](/docs/ai/code/) — The AI coding agent that uses tool calling
- [Models & Allocations](/docs/ai/code/models) — Discovering and switching models
- [AI Keys](/docs/ai/ai-keys/) — Programmatic access through the gateway
# AI Usage
> Source: https://parallelworks.com/docs/ai/ai-usage
# AI Usage
The **AI Usage** dashboard tracks spend, tokens, and budget allocations across your AI providers. Every request through the AI gateway is metered, so you can see how much your Chat conversations and [AI keys](/docs/ai/ai-keys) are costing, and where that usage is going.
To open the dashboard, navigate to **AI** > **AI Usage** in the sidebar.
## Your Usage
The dashboard summarizes your own usage over a selectable time range of the last **7**, **30**, or **90** days:
- **Total Spend** — your AI spend over the selected period
- **Tokens Used** — total tokens, split into input and output tokens
- **Allocations** — the budget allocations you're permitted to draw from
The **Usage over time** chart shows your daily usage across the period, and the breakdown chart splits your usage by **Model** or **API key** — use the grouping toggle to switch between the two.
## Organization Usage
Organization admins see an additional **Organization** tab that aggregates AI usage across the whole organization. Along with total spend, it summarizes:
- **Active Users** — users with AI activity in the selected period
- **Total Tokens** — organization-wide input and output tokens
The organization breakdown can be grouped by **model**, **user**, or **allocation**, and lists each group's cost, tokens, and share of total usage.
## Related Documentation
- [Chat](/docs/ai/chat/) — Using the chat interface
- [AI Providers](/docs/ai/ai-providers/) — Connecting model backends
- [AI Keys](/docs/ai/ai-keys/) — Programmatic access through the gateway
# Best Practices
> Source: https://parallelworks.com/docs/ai/best-practices
# Best Practices
This page covers recommended practices for getting the most out of Chat on the ACTIVATE platform.
## Writing Effective Prompts
The quality of AI responses depends heavily on how you frame your requests.
### Be Specific
Vague prompts produce vague answers. Include relevant details, constraints, and the desired format in your prompt.
| Instead of | Try |
|---|---|
| "Explain Kubernetes" | "Explain how Kubernetes pod scheduling works, including the role of the scheduler and node affinity rules, in about 200 words." |
| "Write a script" | "Write a Bash script that finds all CSV files in a directory and combines them into a single file with one header row." |
### Provide Context
Give the model the background it needs to produce a useful response:
- Describe the environment or system you are working with.
- Mention relevant constraints (language, framework, version).
- Reference earlier parts of the conversation if building on previous responses.
### Use System Messages
If your provider supports system messages, use them to set the model's behavior for the entire conversation. For example, you can instruct the model to respond as a domain expert, use a particular coding style, or avoid certain topics.
### Iterate and Refine
If the first response is not quite right, refine your prompt rather than starting from scratch. Add clarifications, ask for a different format, or request that the model focus on a specific aspect.
## Choosing the Right Model
Different models have different strengths. Selecting the right model for your task improves both response quality and efficiency.
### Standard Models
Standard models (such as GPT-4o, GPT-4o-mini) are best for:
- General-purpose questions and conversation
- Text summarization and generation
- Code generation for straightforward tasks
- Tasks where speed matters more than deep analysis
### Reasoning Models
Reasoning models (such as o1, o3) are best for:
- Complex math, logic, and multi-step problem-solving
- Detailed code review and debugging
- Architectural decisions that require evaluating tradeoffs
- Tasks where accuracy is more important than speed
See [Using Reasoning Models](/docs/ai/chat/using-reasoning-models) for details on reasoning effort configuration.
### Cost Considerations
Larger and more capable models consume more tokens and may have higher usage costs. When working on routine tasks, consider using a smaller or faster model to conserve resources. Reserve more powerful models for tasks that genuinely benefit from their capabilities.
## Working with File Attachments
File attachments allow you to provide the model with additional context beyond what fits in a text prompt.
### Keep Documents Focused
Rather than uploading a large document and asking a broad question, extract the relevant section or upload a smaller, targeted file. This helps the model focus on the content that matters and reduces token usage.
### Use the Right File Type
- **Code files** -- Attach source code files directly for code review, debugging, or analysis tasks.
- **Text and Markdown** -- Use plain text or Markdown for structured information, notes, or specifications.
- **PDFs and documents** -- Upload reports, papers, or documentation that the model can reference when answering your questions.
### Be Aware of Size Limits
Regular files have a maximum size of 25 MB, and documents have a maximum size of 100 MB. If a file exceeds these limits, split it into smaller parts or extract the relevant sections.
See [Attaching Files](/docs/ai/chat/attaching-files) for supported formats and detailed usage instructions.
## Collaboration Tips
Chat's sharing and branching features support team workflows.
### Share with Appropriate Permissions
- Use **View** permission for stakeholders who need to review the conversation without modifying it.
- Use **Collaborate** permission for team members who need to actively contribute messages.
- Share at the group level rather than managing individual access, so permissions stay current as team membership changes.
See [Sharing Conversations](/docs/ai/chat/sharing-conversations) for detailed instructions.
### Use Branching for Exploration
When evaluating different approaches, create branches from the same message rather than cluttering a single thread. Each branch maintains its own context, allowing you to compare model responses to different prompts or explore alternative solutions side by side.
See [Branching Conversations](/docs/ai/chat/branching-conversations) for details.
### Document Decisions
Use the conversation itself as a record of your analysis. When you reach a conclusion, summarize the decision in a follow-up message so that anyone reviewing the shared conversation can quickly understand the outcome.
## Security Considerations
### Sensitive Data
Be mindful of the data you include in prompts and file attachments. Messages are sent to the configured AI provider endpoint, which may be hosted externally.
- For sensitive or proprietary data, use a **session tunnel** provider that routes requests to a model running on your own compute infrastructure. See [Session Tunnels](/docs/ai/ai-providers/session-tunnels).
- Avoid including credentials, API keys, or personally identifiable information in prompts.
### API Key Management
If you manage AI providers, follow these practices for API key security:
- **Rotate keys regularly** -- Update API keys in the provider configuration on a regular schedule.
- **Use the minimum required permissions** -- Configure provider API keys with only the permissions needed for chat completions.
- **Monitor usage** -- Review token usage and access patterns through your provider's dashboard to detect unexpected activity.
### Provider Permissions
Limit provider access to the groups and users who need it. Review and audit provider permissions periodically to ensure that only authorized teams have access.
See [Managing Provider Permissions](/docs/ai/ai-providers/managing-permissions) for details.
## Related Documentation
- [Chat Overview](/docs/ai/chat) - Feature summary and capabilities
- [Getting Started with Chat](/docs/ai/chat/getting-started) - First-time setup walkthrough
- [AI Providers](/docs/ai/ai-providers) - Provider configuration and management
- [Troubleshooting](/docs/ai/chat/troubleshooting) - Common issues and solutions
# Chat
> Source: https://parallelworks.com/docs/ai/chat
# Chat
Chat provides a full-featured chat interface for interacting with large language models directly within ACTIVATE. You can have conversations with AI models from multiple providers, attach files for context, branch conversations to explore different approaches, and share conversations with your team.
:::info Feature may not be available on all platforms
Chat requires at least one AI provider to be configured. If you do not see the **Chat** option in your ACTIVATE account, contact your administrator.
:::
## Access Methods
You can interact with Chat in three ways:
- **Web UI** -- Open **Chat** from the sidebar navigation to use the full-featured chat interface with file attachments, conversation branching, and message history.
- **CLI** -- Run `pw code` for an AI coding agent in your terminal. Unlike Chat, its sessions are stored locally on your machine, not in your account. See [pw code](/docs/ai/code).
- **API** -- Send requests to the OpenAI-compatible API endpoint at `/api/openai/v1/chat/completions` for programmatic access through the AI gateway. See [AI Keys](/docs/ai/ai-keys) for authentication and model ID format.
## Capabilities
- **Multi-provider support** -- Connect to Azure OpenAI, custom OpenAI-compatible endpoints, or models running on your compute clusters via session tunnels.
- **File attachments** -- Attach documents, images, and other files to your messages for additional context. Regular files up to 25 MB and documents (PDF, text, CSV, Office files) up to 100 MB are supported.
- **Conversation branching** -- Edit previous messages or regenerate responses to create conversation branches. Navigate between branches to compare different approaches.
- **Sharing and collaboration** -- Share conversations with your team for read-only viewing or collaborative editing.
- **Reasoning models** -- Use reasoning models (such as o1 and o3) that show their thinking process and support configurable reasoning effort.
- **Streaming responses** -- Responses stream in real time as the model generates them, so you can read output as it arrives.
## Related Documentation
- [Getting Started](/docs/ai/chat/getting-started) -- Send your first message
- [Attaching Files](/docs/ai/chat/attaching-files) -- Add files to your conversations
- [Branching Conversations](/docs/ai/chat/branching-conversations) -- Explore alternative conversation paths
- [Sharing Conversations](/docs/ai/chat/sharing-conversations) -- Collaborate with your team
- [Using Reasoning Models](/docs/ai/chat/using-reasoning-models) -- Work with reasoning models
- [pw code](/docs/ai/code) -- The AI coding agent in your terminal
- [AI Providers](/docs/ai/ai-providers) -- Configure AI providers
- [AI Keys](/docs/ai/ai-keys) -- Programmatic access through the gateway
- [Troubleshooting](/docs/ai/chat/troubleshooting) -- Resolve common issues
# Attaching Files
> Source: https://parallelworks.com/docs/ai/chat/attaching-files
# Attaching Files
Chat supports file attachments, allowing you to include documents, images, and other files as context for your conversations. Attached files are sent alongside your messages so the AI model can reference their content when generating responses.
## Supported File Types
You can attach the following file types:
| Category | Formats |
|----------|---------|
| Documents | PDF, TXT, CSV, DOC, DOCX, XLS, XLSX, PPT, PPTX |
| Images | PNG, JPG, JPEG, GIF, WebP, and other common image formats |
## Size Limits
File size limits depend on the file type:
- **Documents** (PDF, TXT, CSV, XLSX, DOCX, PPTX) -- up to **100 MB** per file
- **All other files** (images, etc.) -- up to **25 MB** per file
- **Maximum files per message** -- up to **10 files**
If a file exceeds the size limit for its type, the upload is rejected with an error message indicating the maximum allowed size.
## How to Attach Files
There are two ways to attach files to a message:
### Drag and Drop
Drag one or more files from your file manager directly into the chat area. A drop zone overlay appears to confirm the drop target. Release the files to begin uploading.
### File Picker
Click the attachment button in the chat input area to open a file picker. Select one or more files and confirm. The selected files are uploaded immediately.
## Upload Process
When you add files, each file shows an upload progress indicator. Once uploaded, the file appears as a chip showing the filename and file size. You can remove an attachment before sending your message by clicking the remove button on the file chip.
Files can be uploaded before a conversation exists. These standalone attachments are associated with the conversation when you send your first message.
## Viewing Attachments in Messages
Attachments appear below the message content:
- **Images** are displayed as inline thumbnails that you can view directly in the chat.
- **Documents and other files** appear as downloadable file chips showing the filename and size. Click on a file chip to download the attachment.
## Managing Attachments
- You can view all attachments associated with a conversation.
- Attachments can be downloaded at any time by clicking on them in the message history.
- When a conversation is deleted, all of its attachments are also deleted.
- Only the attachment owner can delete individual attachments.
## Limitations
- File content processing depends on the capabilities of the selected AI model. Not all models support all file types.
- Very large files may increase response times as the model processes the additional context.
- Image support requires a model that accepts multimodal input (text and images).
## Related Documentation
- [Getting Started](/docs/ai/chat/getting-started) -- Send your first message
- [Chat Overview](/docs/ai/chat) -- Feature overview
- [Troubleshooting](/docs/ai/chat/troubleshooting) -- Resolve file upload issues
# Branching Conversations
> Source: https://parallelworks.com/docs/ai/chat/branching-conversations
# Branching Conversations
Chat uses a tree-based message structure rather than a simple linear history. This means you can create branches at any point in a conversation to explore alternative responses, compare different approaches, or refine your prompts without losing previous work.
## How Branching Works
Every message in a conversation has a parent message (except the first message, which is the root). When you edit a previous message or regenerate an AI response, a new branch is created from that point. The original branch is preserved, and you can switch between branches at any time.
This tree structure means a single conversation can contain multiple parallel threads of discussion, all sharing the same earlier context.
## Creating a Branch
There are two ways to create a new branch:
### Editing a Message
1. Hover over one of your messages to reveal the action buttons.
2. Click the **Edit** button.
3. Modify the message content in the editor that appears.
4. Click **Send** to submit the edited message.
A new branch is created starting from the edited message. The AI generates a fresh response based on your updated input. The original message and its response remain available on the previous branch.
### Regenerating a Response
1. Hover over an AI response to reveal the action buttons.
2. Click the **Regenerate** button.
The model generates a new response to the same prompt. This creates a sibling branch from the same parent message. You can regenerate multiple times to get different responses and compare them.
## Navigating Between Branches
When a message has sibling branches (multiple responses to the same parent), a branch navigator appears below the message. The navigator shows the current branch position (for example, "2/3") and provides arrow buttons to switch between siblings.
Clicking the left or right arrow loads the sibling message and its entire downstream conversation thread. The branch navigator only appears at messages where the conversation actually diverges.
## Active Branch
Each conversation tracks an **active branch**, which determines which path through the message tree is displayed by default when you open the conversation. The active branch updates automatically as you send messages or navigate to different branches.
## Use Cases
Branching is useful in several scenarios:
- **Comparing approaches** -- Ask the same question with different phrasings to see how the model responds differently, without starting a new conversation.
- **Exploring alternatives** -- Regenerate a response multiple times and keep all versions for comparison.
- **Iterating on prompts** -- Edit an earlier message to refine your prompt while preserving the original conversation path.
- **A/B testing** -- Test different instructions or system configurations within the same conversation context.
## Related Documentation
- [Getting Started](/docs/ai/chat/getting-started) -- Send your first message
- [Chat Overview](/docs/ai/chat) -- Feature overview
- [Sharing Conversations](/docs/ai/chat/sharing-conversations) -- Collaborate with your team
# Getting Started with Chat
> Source: https://parallelworks.com/docs/ai/chat/getting-started
# Getting Started with Chat
This guide walks you through sending your first message in Chat, selecting a model, and managing your conversation history.
## Prerequisites
Before you can use Chat, at least one AI provider must be configured and accessible to you. Providers can be added by you or shared with you by an administrator or team member. See [AI Providers](/docs/ai/ai-providers) for setup instructions.
## Opening the Chat Interface
Click **Chat** in the sidebar navigation to open the Chat interface. If no providers are configured, you will see a prompt to add one.
When providers are available, the chat page displays a greeting and a set of suggested prompts to help you get started.
## Selecting a Provider and Model
Use the model selector in the toolbar at the top of the chat interface to choose which AI model to use. Models are grouped by provider and listed with human-friendly names (for example, **my-azure-provider / gpt-4o**). If a provider offers multiple models, each one appears as a separate option.
Session tunnel models (models running on your compute clusters) also appear in this list when an active tunnel is available.
## Sending a Message
1. Type your message in the input field at the bottom of the chat interface, or click one of the suggested prompts.
2. Optionally attach files by clicking the attachment button or dragging files into the chat area.
3. Press **Enter** or click the send button.
Your message is sent to the selected model, and a new conversation is created automatically if one does not already exist.
## Understanding Streaming Responses
Chat streams responses in real time. As the model generates its reply, text appears incrementally in the chat interface. A green indicator is shown while the response is streaming.
For reasoning models, a "Thought for..." indicator appears after the response completes, showing how long the model spent in its thinking phase. You can click this indicator to view the model's reasoning process.
## Managing Conversation History
Your conversations are saved automatically and listed in the sidebar. Conversations are sorted by most recently updated.
### Viewing Past Conversations
Click any conversation in the sidebar to reopen it. The full message history, including any branches, is restored.
### Renaming a Conversation
Conversations can be renamed by updating the title. This helps you organize and find past conversations.
### Deleting a Conversation
Only the conversation owner can delete a conversation. Deleting a conversation also removes all associated attachments and sharing permissions.
## Next Steps
- [Attaching Files](/docs/ai/chat/attaching-files) -- Learn how to include files in your messages
- [Branching Conversations](/docs/ai/chat/branching-conversations) -- Explore alternative responses
- [Sharing Conversations](/docs/ai/chat/sharing-conversations) -- Share with your team
- [Using Reasoning Models](/docs/ai/chat/using-reasoning-models) -- Use models with extended thinking
- [pw code](/docs/ai/code) -- Work with AI from the command line
## Related Documentation
- [Chat Overview](/docs/ai/chat) -- Feature overview and access methods
- [AI Providers](/docs/ai/ai-providers) -- Configure AI providers
- [Troubleshooting](/docs/ai/chat/troubleshooting) -- Resolve common issues
# Sharing Conversations
> Source: https://parallelworks.com/docs/ai/chat/sharing-conversations
# Sharing Conversations
Chat allows you to share conversations with other members of your organization. You can grant read-only access for review purposes or full collaboration access that lets others contribute messages to the conversation.
## Permission Levels
Chat supports two permission levels for shared conversations:
- **View** -- Recipients can read the entire conversation, including all messages and branches, but cannot add new messages or modify existing content.
- **Collaborate** -- Recipients can read the conversation and add their own messages. This is useful for team problem-solving or collaborative analysis sessions.
:::info Owner Only
Only the conversation owner can manage sharing settings. If you need access to a conversation, ask the owner to share it with you.
:::
## How to Share a Conversation
1. Open the conversation you want to share.
2. Click the **Share** icon in the conversation header.
3. In the **Share Conversation** dialog, configure access at the organization or group level.
### Organization-Wide Access
To share with everyone in your organization:
1. Check **Anyone in the organization can view** to grant view access to all organization members.
2. Optionally check **Allow collaboration (edit messages)** to upgrade the permission from view-only to collaborate.
### Group Access
To share with specific groups:
1. In the **Group Access** section, use the **Add groups** dropdown to select one or more groups.
2. For each group, choose the permission level using the dropdown next to the group name:
- **View only** -- Members of the group can read the conversation.
- **Can collaborate** -- Members of the group can read and add messages.
3. To remove a group's access, click the trash icon next to the group entry.
After configuring the desired permissions, click **Save** to apply the changes.
## Accessing Shared Conversations
Conversations that have been shared with you appear in your conversation list. You can identify shared conversations by the presence of the share indicator. Depending on your permission level:
- **View access** -- You can open and read the conversation but cannot send messages.
- **Collaborate access** -- You can open the conversation and send messages as if it were your own.
## Managing and Revoking Access
To modify or remove access for a shared conversation:
1. Open the conversation and click the **Share** icon.
2. Change permission levels using the dropdown next to each group.
3. Remove a group by clicking the trash icon.
4. Uncheck the organization-wide access checkbox to revoke access for the entire organization.
5. Click **Save** to apply changes.
Changes take effect immediately. Users who lose access will no longer see the conversation in their list.
## Collaboration Tips
- **Use branches for parallel exploration** -- When collaborating, each team member can create branches from the same message to explore different approaches without interfering with each other's work.
- **Set clear permissions** -- Use view-only access for stakeholders who need to review progress and collaborate access for team members who need to actively contribute.
- **Share with groups, not individuals** -- Sharing at the group level makes it easier to manage access as team membership changes.
## Related Documentation
- [Branching Conversations](/docs/ai/chat/branching-conversations) - Create parallel conversation threads
- [Getting Started with Chat](/docs/ai/chat/getting-started) - First-time setup walkthrough
- [Best Practices](/docs/ai/best-practices) - Tips for effective AI collaboration
# Troubleshooting
> Source: https://parallelworks.com/docs/ai/chat/troubleshooting
# Troubleshooting
This page covers common issues you may encounter when using Chat and how to resolve them.
## No Providers Available
**Symptom:** The provider or model dropdown is empty, or you see a message indicating no providers are configured.
**Cause:** No AI providers have been set up for your organization, or you do not have permission to use the available providers.
**Solution:**
- Contact your organization administrator and ask them to configure an AI provider. See [AI Providers](/docs/ai/ai-providers) for setup instructions.
- If providers exist but you cannot see them, ask the administrator to grant your group access to the provider. See [Managing Provider Permissions](/docs/ai/ai-providers/managing-permissions).
## Connection Errors
**Symptom:** You receive an error when sending a message, such as "Failed to connect" or "Provider endpoint unreachable."
**Cause:** The underlying AI provider endpoint may be unavailable, misconfigured, or experiencing an outage.
**Solution:**
- Verify that the provider endpoint is correct and accessible. For custom OpenAI-compatible providers, confirm that the endpoint URL is reachable from the ACTIVATE platform.
- For session tunnel providers, ensure the tunnel is active and the compute session is running. Tunnels are only available while the associated session is active. See [Session Tunnels](/docs/ai/ai-providers/session-tunnels).
- For Azure OpenAI providers, verify the API key and endpoint in the provider configuration. Check the [Azure status page](https://status.azure.com/) for any ongoing outages.
- Try sending another message after a few moments. Transient network issues may resolve on their own.
## Slow or Stalled Responses
**Symptom:** The AI response takes a long time to appear or the loading indicator runs indefinitely.
**Cause:** This can happen for several reasons:
- **Reasoning models** use an extended thinking phase before generating a response. This is expected behavior and can take significantly longer than standard models. See [Using Reasoning Models](/docs/ai/chat/using-reasoning-models).
- **High model load** on the provider side can cause delays, especially with shared or rate-limited endpoints.
- **Large conversation context** can increase processing time as the model processes more tokens.
**Solution:**
- If using a reasoning model, wait for the response to complete. The thinking phase may take 30 seconds or longer for complex prompts.
- For standard models, try starting a new conversation to reduce context size.
- If the issue persists, check with your administrator whether the provider endpoint is under heavy load.
## File Upload Failures
**Symptom:** A file upload fails or you see an error when attaching a file to a message.
**Cause:** The file may exceed size limits or be in an unsupported format.
**Solution:**
- Check the file size. Regular files have a maximum size of 25 MB, while documents have a maximum size of 100 MB.
- Verify that the file type is supported. Common supported types include text files, code files, PDFs, images, and office documents.
- Try uploading a smaller file or splitting large files into smaller parts.
- See [Attaching Files](/docs/ai/chat/attaching-files) for detailed information on supported formats and size limits.
## Model Not Listed
**Symptom:** A specific model you expect to see is not available in the model dropdown.
**Cause:** The model may not be deployed on the provider, or the provider configuration may not include it.
**Solution:**
- Verify with your administrator that the desired model is deployed and available on the provider endpoint.
- For Azure OpenAI providers, confirm that the model deployment name is correctly configured.
- For custom providers, ensure the endpoint's `/v1/models` response includes the model you are looking for.
- Check that you have permission to use the provider that hosts the model.
## CLI Chat Issues
**Symptom:** The `pw code` command fails or cannot connect.
**Cause:** Authentication, network, or model identifier issues.
**Solution:**
- Verify you are authenticated: run `pw auth` and paste your credential when prompted.
- Confirm the model identifier is correct. It must use the format `owner:provider-name/model-name` (for example, `jane.doe:my-provider/gpt-4o`). Run `pw ai models ls` to see available models.
- Check your network connection to the ACTIVATE platform.
- See [pw code](/docs/ai/code) for detailed setup instructions, and [pw code troubleshooting](/docs/ai/code/troubleshooting) for agent-specific issues.
## Getting Help
If the solutions above do not resolve your issue:
1. Check the [Chat overview](/docs/ai/chat) for general guidance on available features.
2. Review the [AI Providers](/docs/ai/ai-providers) documentation to verify your provider configuration.
3. Contact your organization administrator for platform-specific assistance.
4. Reach out to Parallel Works support for further troubleshooting.
## Related Documentation
- [Getting Started with Chat](/docs/ai/chat/getting-started) - First-time setup walkthrough
- [Attaching Files](/docs/ai/chat/attaching-files) - File upload details and limits
- [Using Reasoning Models](/docs/ai/chat/using-reasoning-models) - Understanding reasoning model behavior
- [AI Providers](/docs/ai/ai-providers) - Provider configuration and management
# Using Reasoning Models
> Source: https://parallelworks.com/docs/ai/chat/using-reasoning-models
# Using Reasoning Models
Reasoning models such as OpenAI's o1 and o3 series use an extended thinking process before generating a response. Chat supports these models and surfaces their reasoning output so you can follow the model's chain of thought.
## What Are Reasoning Models?
Standard chat models generate responses token by token in a single pass. Reasoning models add a **thinking phase** before the final response. During this phase, the model works through the problem step by step, considering different approaches and verifying its logic before producing an answer.
This thinking process is especially beneficial for:
- Complex math and logic problems
- Multi-step analysis and planning
- Code debugging and architectural decisions
- Tasks that require careful evaluation of tradeoffs
## How Reasoning Models Differ
When you use a reasoning model in Chat, the experience differs from standard models in several ways:
- **Longer response times** -- The thinking phase adds processing time before the response begins streaming. This is normal and expected.
- **Reasoning content** -- The model's internal reasoning may be displayed alongside the final response, allowing you to follow how it arrived at its answer.
- **Reasoning tokens** -- Reasoning models consume additional tokens for the thinking phase. These reasoning tokens count toward the model's context window and usage.
## Reasoning Effort
Some reasoning models support a **reasoning effort** parameter that controls how much time the model spends thinking before responding. Chat supports three effort levels:
- **Low** -- Minimal reasoning. The model spends less time thinking, resulting in faster responses. Best for straightforward questions where deep analysis is not needed.
- **Medium** -- Balanced reasoning. A good default for most tasks.
- **High** -- Maximum reasoning. The model takes more time to think through the problem thoroughly. Best for complex problems where accuracy is critical.
:::info Model Support
Reasoning effort is only available for models that support it. If the selected model does not support reasoning effort, the setting has no effect.
:::
## When to Use Reasoning Models
**Use reasoning models when:**
- The task involves complex logic, math, or multi-step problem-solving.
- You need the model to carefully evaluate multiple options before answering.
- Accuracy matters more than response speed.
- You are debugging intricate code or analyzing system architectures.
**Use standard models when:**
- You need quick, conversational responses.
- The task is straightforward (summarization, simple Q&A, text generation).
- Low latency is important.
- You want to minimize token usage.
## Working with Reasoning Output
When a reasoning model is used, Chat may display the model's reasoning process alongside the final response. This reasoning content shows the steps the model took to arrive at its answer. Reviewing this output can help you:
- Verify the model's logic and catch errors in its reasoning.
- Understand why the model chose a particular approach.
- Refine your prompt based on how the model interpreted your request.
## Related Documentation
- [Getting Started with Chat](/docs/ai/chat/getting-started) - First-time setup walkthrough
- [Best Practices](/docs/ai/best-practices) - Tips for model selection and effective prompting
- [AI Providers](/docs/ai/ai-providers) - Configure providers that offer reasoning models
# pw code
> Source: https://parallelworks.com/docs/ai/code
# pw code
`pw code` is an AI coding agent that runs in your terminal. It can read, write, and edit the files in your workspace (the directory you start it in), run shell commands, and carry out multi-step tasks autonomously using tool calling. Responses stream in real time and are rendered as formatted markdown directly in your terminal.
:::info Feature may not be available on all platforms
`pw code` requires at least one AI provider to be configured. If no models are available in your account, contact your administrator.
:::
## Prerequisites
- **PW CLI installed**: See the [CLI documentation](/docs/cli) for installation instructions.
- **Authenticated**: Run `pw auth` and paste your credential when prompted. On ACTIVATE user workspaces and clusters the CLI is pre-authenticated. See [Authentication](/docs/cli#authentication).
- **An AI provider**: At least one AI provider must be configured by you or shared with you. See [AI Providers](/docs/ai/ai-providers).
## Quick Start
Start the agent from the directory you want to work in:
```bash
pw code
```
If you do not specify a model, `pw code` opens an interactive picker so you can choose one; there is nothing to look up first. Inside a session, run `/model` to reopen the picker and switch at any time.
You can also start with a specific model by passing its ID:
```bash
pw code owner:provider-name/model-name
```
Model IDs have the form `owner:provider-name/model-name`. For a personal provider, the owner is the username of the person who owns the provider (for example `Jake.Thayne:openai/gpt-5.2`). Organization provider models use the `org:` prefix and require a [budget allocation](/docs/ai/code/models#allocations), a named spending budget your organization grants you. When you need an ID outside a session, such as for [non-interactive runs](/docs/ai/code/non-interactive), list them with `pw ai models ls`.
### What to expect on first launch
If the directory contains configuration files (a `.mcp.json` file or a `.agents/` folder), `pw code` lists them at first launch and asks whether to apply them. See [Workspace Trust](/docs/ai/code/settings#workspace-trust).
By default, the agent edits workspace files freely but asks before each shell command. See [Permissions](/docs/ai/code/permissions).
A short session looks like this:
fix the failing test in parser_test.goI'll look at the failing test and fix the parser.214 linesreturn cfgreturn cfg, nilok
## Capabilities
- **[Sessions & Resume](/docs/ai/code/sessions)**: Every run is saved as a local session on your machine that you can resume later, from the command line or an interactive picker.
- **[Permissions](/docs/ai/code/permissions)**: Control what the agent may do without asking, from read-only exploration to fully autonomous edits.
- **[Interface & Shortcuts](/docs/ai/code/interface)**: The full-screen terminal interface, keyboard shortcuts, `@` file references, and `!` shell mode.
- **[Models & Allocations](/docs/ai/code/models)**: Pick from the models your providers offer, and browse budget allocations interactively when using organization providers.
- **[Settings](/docs/ai/code/settings)**: Global and per-workspace configuration, and the in-session `/settings` menu.
- **[Slash Commands](/docs/ai/code/slash-commands)**: Type `/` in a session to run built-in commands, plus custom commands defined in your project.
- **[Project Instructions](/docs/ai/code/project-instructions)**: Guide the agent with an `AGENTS.md` file checked into your project.
- **[MCP Servers](/docs/ai/code/mcp)**: Connect Model Context Protocol servers to give the agent additional tools.
- **[Subagents](/docs/ai/code/subagents)**: Delegate work to subagents that run in parallel alongside your session.
- **[Custom Agents](/docs/ai/code/custom-agents)**: Define specialized agents with their own instructions, tool access, and model.
- **[Non-Interactive Mode](/docs/ai/code/non-interactive)**: Run one-shot prompts with text or JSON output for scripting and automation.
## Command-Line Flags
| Flag | Description |
| --- | --- |
| `-m`, `--model` | Model ID (can also be passed as a positional argument). |
| `--allocation` | Budget allocation name. Required for `org:` provider models. |
| `-p`, `--prompt` | Send a single prompt and exit. See [Non-Interactive Mode](/docs/ai/code/non-interactive). |
| `-w`, `--workspace` | Workspace root directory. Defaults to the current directory. |
| `--permission-mode` | `read-only`, `accept-edits` (default), `bypass-permissions`, or `plan`. See [Permissions](/docs/ai/code/permissions). |
| `--allowedTools` | Tools pre-approved without prompting, for example `ReadFile` or `'Bash(git status:*)'`. |
| `--add-dir` | Directories outside the workspace the agent may read without prompting (repeatable). |
| `-o`, `--output` | Output format for one-shot runs: `text` (default) or `json`. |
| `-r`, `--resume` | Resume a local session by ID or `latest`; used alone, opens an interactive session picker. |
| `--no-tools` | Disable tool calling (chat-only mode). |
| `--agent` | Run a [custom agent](/docs/ai/code/custom-agents) definition as the main session. |
For the complete command reference, see [pw code](/docs/cli/pw/code).
## pw code and Your Account Chats
`pw code` sessions are local to your machine: they are not uploaded to your account and do not appear in the [Chat](/docs/ai/chat) list in the web interface. See [Sessions & Resume](/docs/ai/code/sessions) for how local sessions are stored.
Chats saved to your account, such as conversations from the web Chat interface, are managed separately with the `pw ai chats` commands:
```bash
# List chats saved to your account
pw ai chats ls
# View a chat's messages
pw ai chats get
# Delete a chat
pw ai chats delete
```
## Related Documentation
- [Usage & Costs](/docs/ai/code/usage-and-costs): Token usage and cost estimates
- [Troubleshooting](/docs/ai/code/troubleshooting): Resolve common issues
- [Chat](/docs/ai/chat): The web chat interface
- [AI Providers](/docs/ai/ai-providers): Configure AI providers
- [pw code command reference](/docs/cli/pw/code): Full CLI reference
# Custom Agents
> Source: https://parallelworks.com/docs/ai/code/custom-agents
# Custom Agents
A custom agent is a reusable, named agent definition: a markdown file that gives an agent a description, a specialization prompt, and optional limits on its tools, permissions, and model. Once defined, a custom agent can be used two ways:
- **As a subagent type**: when the agent [delegates work](/docs/ai/code/subagents), it can pick your custom agent by name and the subagent runs with that definition's prompt and limits.
- **As the main session**: launch `pw code --agent ` to run a definition as the agent you talk to directly.
## Where Definitions Live
`pw code` looks for `.md` definition files in these directories, in order (when the same agent name appears in more than one place, the earlier directory wins):
1. `/.agents/agents/`: project definitions, checked in with your code
2. `~/.config/agents/agents/`: your personal definitions (respects `XDG_CONFIG_HOME`)
Directories are scanned recursively, so you can organize definitions into subfolders. An agent's identity comes from its `name` field (or its filename), never its path. The name `fork` is reserved for [conversation forks](/docs/ai/code/subagents#forking-the-conversation); a definition named `fork` is ignored with a warning.
:::note Project definitions require approval
Definition files in the workspace are part of the configuration `pw code` asks you to approve at launch. See [Workspace Trust](/docs/ai/code/settings#workspace-trust).
:::
## File Format
A definition is YAML frontmatter followed by a markdown body. The body is the agent's **specialization prompt**. It is appended to the standard system prompt, so the agent keeps all its normal abilities and gains your specialization on top.
| Field | Meaning |
| --- | --- |
| `name` | The agent's name. Defaults to the filename without `.md`. |
| `description` | What this agent is for. This is how the main agent decides when to delegate to it. Write it like a job description. |
| `tools` | Comma-separated allowlist of tool names the agent may use (for example `ReadFile, GrepSearch, GlobSearch, Bash`). Empty means all tools. |
| `disallowedTools` | Comma-separated denylist. Deny always wins over `tools`. |
| `model` | Model this agent runs on (`owner:provider-name/model-name`). Empty inherits; see [model resolution](/docs/ai/code/subagents#models-for-subagents). |
| `permissionMode` | Requested permission mode: `read-only`, `plan`, `accept-edits`, or `bypass-permissions`. Can narrow the session's mode, never widen it (see [Permission Clamping](#permission-clamping-for-definition-authors)). |
| `isolation` | `worktree` runs the agent's delegated tasks in a temporary git worktree, keeping its changes out of your working tree. |
| `maxTurns` | Cap on agentic iterations per delegated task. Unset means unlimited. |
| `background` | `true` forces this agent's tasks to always run detached, even when an inline result was requested. |
| `color` | Display color for the agent's switcher dot and task blocks: `blue`, `green`, `yellow`, `purple`, `cyan`, `orange`, `pink`, or `red`. |
| `initialPrompt` | Auto-submitted as the first message when the definition runs as the main session via `--agent`. |
Frontmatter values are single-line. `isolation`, `background`, and `color` shape how the agent behaves and displays when it runs as a subagent; they do not apply to a `--agent` main session.
## Example Definition
`.agents/agents/reviewer.md`:
```markdown
---
name: reviewer
description: Reviews code changes for correctness, style, and missed edge cases. Use for read-only review passes over a diff or a set of files.
tools: ReadFile, GrepSearch, GlobSearch, Bash
permissionMode: read-only
model: owner:provider-name/model-name
color: purple
maxTurns: 30
---
You are a meticulous code reviewer.
Review the changes you are pointed at for:
- Correctness bugs and unhandled edge cases
- Consistency with the surrounding code's style and conventions
- Missing or misleading tests
Report findings as a prioritized list. Cite file paths and line numbers.
Do not modify any files.
```
## Using a Custom Agent for Delegated Work
You do not invoke a custom agent directly. The main agent sees every definition's name and description and picks the right type when it delegates. You can also steer it explicitly: "use the reviewer agent to check this diff."
In the [agent switcher](/docs/ai/code/subagents#the-agent-switcher), a custom agent's row shows its type name next to its task description, and its task block in the transcript is titled with the type name instead of `Task`. The definition's `color` (or an automatically assigned one) marks its dot in both places.
### Worktree Isolation
An agent defined with `isolation: worktree` runs its delegated tasks in a temporary git worktree (a separate checkout of your repository) so its changes never touch your working tree while you and other agents keep working. This requires the workspace to be a git repository with at least one commit; when a worktree cannot be created, the task falls back to sharing the workspace and says so in its task block.
The subagent's report names the worktree path so you (and the main agent) know where its changes live. A worktree with no changes is cleaned up automatically; a worktree holding uncommitted changes or new commits is **kept**, and resuming the session later puts the revived subagent back inside it.
## Running a Definition as the Main Session
Launch a definition as the agent you talk to:
```bash
pw code --agent reviewer
```
- The definition's `model` and `permissionMode` are used unless you override them on the command line.
- Its `tools`, `disallowedTools`, and `maxTurns` limits apply exactly as they would to a subagent.
- Its body is appended to the system prompt as the session's specialization.
- Its `initialPrompt`, if set, is submitted automatically as the first message; in a one-shot run (`-p`), it is prepended to your prompt instead.
Naming an agent that does not exist fails with the list of available names.
### Ad-Hoc Definitions with --agents
`--agents` takes JSON definitions keyed by name: the same fields as frontmatter, with `tools` and `disallowedTools` as arrays and the specialization body in a `prompt` field. They merge over the definition files (an ad-hoc definition with the same name wins) and are available both for delegation and for `--agent`:
```bash
pw code --agents '{
"changelog": {
"description": "Drafts changelog entries from recent commits",
"tools": ["ReadFile", "Bash"],
"permissionMode": "read-only",
"prompt": "You draft concise changelog entries. Read git log and summarize user-facing changes."
}
}'
```
## Permission Clamping for Definition Authors
A custom agent can restrict what a subagent may do, but it can never grant more than the session it runs in:
- **Modes only narrow.** Modes rank `read-only` < `plan` < `accept-edits` < `bypass-permissions`. If a definition requests a mode above the session's, it is clamped down to the session's mode, and the clamp is noted in the subagent's task block. A `read-only` definition stays read-only in any session. The requested mode also acts as a live ceiling: if the session's mode changes while the subagent is running, the subagent follows the change, up to the definition's requested mode and never past the session.
- **Tool scope only narrows.** Allowlists intersect with what the spawning agent may use, and denylists accumulate across every generation, so even with nesting enabled a restricted agent can never spawn a subagent with tools it lacks itself. A definition whose `tools` list has nothing in common with the spawning agent's tools is unusable from that agent, and delegation to it fails with an explanation.
- **Approvals stay per-agent.** When a subagent's command needs approval, the prompt names that agent, and your approval applies to that subagent only.
Write definitions assuming the narrowest session they might run in, and treat `permissionMode` and `tools` as guardrails for the agent's role: a reviewer that cannot write files, a researcher that cannot run shell commands. See [Permissions](/docs/ai/code/permissions) for how modes and approvals work.
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Subagents](/docs/ai/code/subagents): Delegation, the agent switcher, follow-ups, and limits
- [Permissions](/docs/ai/code/permissions): Permission modes and approvals
- [Models & Allocations](/docs/ai/code/models): Model IDs and choosing models
- [Settings](/docs/ai/code/settings): Subagent-related settings
- [Project Instructions](/docs/ai/code/project-instructions): Per-project guidance for the agent
- [Non-Interactive Mode](/docs/ai/code/non-interactive): One-shot runs with -p
# Interface & Shortcuts
> Source: https://parallelworks.com/docs/ai/code/interface
# Interface & Shortcuts
Interactive `pw code` runs in a full-screen terminal interface: a scrollable transcript on top, the message composer at the bottom, and a status line showing the current model, allocation, and token usage. This page covers the interface elements and every keyboard shortcut.
At rest, the bottom of the screen looks like this:
## The Transcript
- **Streaming markdown**: Responses stream in as the model generates them and are rendered as formatted markdown, including highlighted code blocks.
- **Syntax-highlighted diffs**: File edits are shown as diffs with syntax highlighting on the changed lines.
- **Repo banner**: The startup banner includes the repository name and current branch when the workspace is a git repository.
- **Collapsible blocks**: Long tool outputs collapse to a summary line; press Ctrl+O to expand or collapse the most recent one.
- **Jump to bottom**: When you scroll up, a centered **Jump to bottom (ctrl+end) ↓** pill appears; new output stops following until you return to the tail (or press Ctrl+R to re-enable following).
- **Search**: Press Ctrl+F and type to search the transcript; matches are highlighted, Enter/↓ and ↑ step between them, and Esc closes the search.
The mouse wheel always scrolls the transcript. Clicking on interface elements is off by default; enable the **Mouse clicks** option in `/settings` if you want clicks to select picker rows and toggle blocks.
## Keyboard Shortcuts
Press ? at an empty prompt to toggle the shortcuts overlay in the session itself.
| Key | Action |
| --- | --- |
| Enter | Send the message. While the agent is working, the message is queued and sent automatically when the turn ends. |
| Shift+Enter | Insert a newline (Alt+Enter or Ctrl+J on terminals that cannot distinguish it). |
| ↑ / ↓ | Recall earlier prompts, including from previous sessions in the same workspace. While the agent is working, ↑ at an empty prompt pulls back your newest queued message for editing. |
| ↓ (past the newest entry) | Move the cursor into the agent switcher when subagents are running. See [Subagents](/docs/ai/code/subagents) for the switcher's own keys. |
| Esc | Close an open overlay; interrupt the running turn or `!` command. At the prompt, press once to arm and again to clear the typed text. |
| Ctrl+C | Interrupt the running turn; with text typed, clear the composer. At an empty prompt, press twice to quit. |
| Ctrl+D | Quit (at an empty prompt). |
| Shift+Tab | Cycle the [permission mode](/docs/ai/code/permissions): `read-only` → `accept-edits` → `bypass-permissions` → `plan`. |
| ? | Toggle the shortcuts overlay (at an empty prompt). |
| / | Open the [slash command](/docs/ai/code/slash-commands) palette. |
| @ | Open the file picker to reference a file. |
| ! | Enter shell mode (see below). |
| Ctrl+O | Expand or collapse the most recent collapsible block. |
| Ctrl+R | Toggle whether the transcript follows new output. In the model picker: refresh the model list. |
| Ctrl+F | Search the transcript. |
| Ctrl+V | Paste: attaches a clipboard image when one is present, otherwise pastes text. |
| Ctrl+L | Clear and redraw the screen. |
| PgUp / PgDn | Scroll the transcript half a screen. |
| Ctrl+Home / Ctrl+End | Jump to the top / bottom of the transcript while scrolled. |
Interrupting a turn restores your last message to the composer so you can edit and resend it. If you had messages queued, they are discarded instead, with a notice.
## Shell Mode
Start a message with ! to run a shell command yourself, without involving the model. The composer's prompt glyph switches to `!` and a hint appears: **enter runs it locally; output is added to the conversation**.
git log --oneline -5
The command runs in your login shell in the workspace directory. Because you typed it yourself, it bypasses the agent's [permission system](/docs/ai/code/permissions) entirely. The command and its output are recorded into the conversation as context, so the agent can refer to them on its next turn, but running a `!` command does **not** start a model turn; the agent only sees the output the next time you send it a message.
Press Esc to interrupt a running command. Commands are limited to two minutes; a hung command is killed rather than freezing the session.
## File References
Type @ followed by part of a file name to open the file picker, which fuzzy-matches against the workspace's files as you type. Use ↑/↓ to move, and Tab or Enter to insert the highlighted path. Selecting a directory keeps the picker open on that directory's contents so you can browse inward. Path-like queries such as `@~/Downloads/` or `@../` browse the filesystem directly, including outside the workspace.
When your message is sent:
- **Text files** referenced with `@` have their contents included with your message (workspace files only). The transcript shows just the `@` reference you typed.
- **Image paths** (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`) are attached as images the model can see. These may point outside the workspace, e.g. `@~/Downloads/screenshot.png`.
## Pasting Images
Press Ctrl+V to paste an image from the clipboard. The image is attached and an `[Image #1]` placeholder is inserted into your message; deleting the placeholder before sending drops the attachment. If the model rejects image input, `pw code` tells you so you can remove the image or switch to a vision-capable model with `/model`.
:::note Over SSH
Inside an SSH session your local clipboard is unreachable, and `pw code` will say so. Copy the file to the remote machine (e.g. with `scp`) and attach it with `@path` instead.
:::
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Slash Commands](/docs/ai/code/slash-commands): The `/` command palette
- [Permissions](/docs/ai/code/permissions): What the permission modes mean
- [Subagents](/docs/ai/code/subagents): The agent switcher and delegated tasks
- [Sessions & Resume](/docs/ai/code/sessions): The session picker
- [Settings](/docs/ai/code/settings): Auto-scroll, mouse clicks, and other preferences
- [Models & Allocations](/docs/ai/code/models): The model picker
# MCP Servers
> Source: https://parallelworks.com/docs/ai/code/mcp
# MCP Servers
MCP ([Model Context Protocol](https://modelcontextprotocol.io)) servers give the agent tools beyond the built-ins, such as querying your issue tracker or searching internal documentation. `pw code` connects to configured servers at startup, local processes or remote endpoints, and offers their tools to the agent alongside the built-in ones. Servers can also expose reusable prompts, which appear as slash commands.
## Managing Servers from the CLI
The `pw code mcp` command group manages server configuration:
```bash
# Add a stdio server (the command goes after --)
pw code mcp add -e API_KEY=secret everything -- npx -y @modelcontextprotocol/server-everything
# Add a remote HTTP server to the shared /.mcp.json
pw code mcp add --transport http -H "Authorization: Bearer token" --scope project context7 https://mcp.context7.com/mcp
# Fill in every value interactively
pw code mcp add
# Inspect configuration
pw code mcp list
pw code mcp get
# Remove a server
pw code mcp remove
```
`add` takes the server name, then a URL for `http`/`sse` servers or a command after `--` for `stdio` servers. Run it with no arguments to be prompted for each value.
| Flag | Meaning |
| --- | --- |
| `--transport` | Server transport: `stdio`, `http`, or `sse` |
| `-e/--env KEY=VALUE` | Environment variable for the server process (repeatable, stdio only) |
| `-H/--header "Key: Value"` | Header sent on every request (repeatable, http/sse only) |
| `--timeout` | Connection timeout for this server |
| `--scope` | Config file the entry is written to (`local`, `agents`, `project`, or `user`) |
| `--force` | Overwrite an existing entry with the same name |
The other subcommands:
- `list` (alias `ls`) shows every configured server across all config files, marking which file is active and which are shadowed. Use `-o json` for machine-readable output.
- `get ` prints one server's configuration (JSON by default, `-o text` for a summary).
- `remove ` (alias `rm`) deletes a server; if the name is defined in more than one file, you choose which one (or pass `--scope`).
See the [CLI reference](/docs/cli/pw/code/mcp) for the full flag list.
## Where Servers Are Configured
Servers live in an `mcpServers` map, the same shape as Claude Desktop and Claude Code, so existing server configs paste in unchanged. Four files can hold the map, from highest to lowest precedence:
| Scope | File | Typical use |
| --- | --- | --- |
| `local` | `/.agents/settings.local.json` | Personal, git-ignored (default for `add`) |
| `agents` | `/.agents/settings.json` | Project settings, shared via version control |
| `project` | `/.mcp.json` | The cross-tool standard MCP file |
| `user` | `~/.config/pw/code.json` | Global, every workspace |
:::warning Files replace, not merge
The runtime server set comes from **one file only**: the highest-precedence file with a non-empty `mcpServers` map supplies the entire set. A higher-precedence file replaces the whole map below it rather than adding to it, so servers defined in a shadowed file are inactive. `pw code mcp add` warns when a write lands in (or creates) a shadowing situation, and `pw code mcp list` shows which file is active.
:::
The three workspace files are part of the configuration `pw code` asks you to approve at launch; until you approve, their servers do not load. See [Workspace Trust](/docs/ai/code/settings#workspace-trust).
## Configuration Format
All four files use the same top-level shape. The `type` field (`"stdio"`, `"http"`, or `"sse"`) is optional. When omitted, the transport is inferred: stdio if `command` is set, HTTP if `url` is set.
```json
{
"mcpServers": {
"local-tools": {
"command": "uvx",
"args": ["some-mcp-server"],
"env": { "API_KEY": "${MY_KEY}" }
},
"remote": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer ${TOKEN}" }
}
}
}
```
- **stdio** servers are spawned as a local process from `command` + `args` and speak MCP over stdin/stdout. Optional `env` adds environment variables. The server must keep stdout clean for the protocol and log to stderr only.
- **http** and **sse** servers are remote endpoints reached via `url`. Optional `headers` are sent on every request (the place for auth tokens).
`${VAR}` in `env` values and `headers` is expanded from your environment, so secrets can stay out of config files.
### Connection Timeout
Each connect attempt is bounded so a dead server cannot hang the session. The timeout is resolved in this order: a per-server `timeout` in the server's config, then the `MCP_TIMEOUT` environment variable, then a 30-second default. Both accept a bare number of milliseconds (`60000`) or a duration string (`"60s"`, `"2m"`).
## Tools and Permissions
Each discovered tool is exposed to the model as `mcp____`: a server named `github` with a `list_prs` tool becomes `mcp__github__list_prs`. MCP tools ask for confirmation before each call, like shell commands. To pre-approve a tool and skip the prompt, add it to your allow rules:
```text
/permissions add mcp__github__list_prs
```
or start the session with `--allowedTools mcp__github__list_prs`. MCP tools are not available in plan mode; in read-only mode only pre-approved tools can run, and in bypass-permissions mode they run without prompting. See [Permissions](/docs/ai/code/permissions).
## Connection Behavior
In interactive sessions, servers connect in the background so startup is never blocked. Each server is announced in the transcript as it comes online, and a server that fails its first attempt is retried with backoff, useful for servers that download packages on first run. Run `/mcp` at any time to see each server's status (connected, connecting, or failed) and the tools it exposes.
In non-interactive mode (`--prompt`), there is only a single turn, so servers connect synchronously before it runs.
## Prompts as Slash Commands
Servers can also expose prompts: reusable prompt templates. Each discovered prompt becomes a slash command named `/mcp____`, shown in the command palette (type `/`) with a usage hint built from the prompt's declared arguments.
Arguments are space-separated and map positionally onto the prompt's declared arguments; quote a value to keep multiple words together, and extra trailing words fold into the last argument:
```text
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login flow" high
```
Running the command renders the prompt on the server and sends the result as a normal agent turn. A missing required argument, an unknown prompt, or a server-side failure is reported in the transcript instead.
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [pw code mcp CLI reference](/docs/cli/pw/code/mcp): Full command and flag reference
- [Permissions](/docs/ai/code/permissions): Permission modes and allow rules
- [Slash Commands](/docs/ai/code/slash-commands): Built-in and custom commands
- [Settings](/docs/ai/code/settings): Other `pw code` configuration
- [Non-Interactive Mode](/docs/ai/code/non-interactive): Running with `--prompt`
# Models & Allocations
> Source: https://parallelworks.com/docs/ai/code/models
# Models & Allocations
`pw code` can run on any chat model your AI providers offer. This page covers how models are identified, how to discover and switch between them, and how budget allocations work for organization providers.
## Model IDs
Model IDs have the form `owner:provider-name/model-name`:
- **Personal providers** are addressed by their owner's username, for example `Jake.Thayne:openai/gpt-5.2`.
- **Your own connected subscriptions** (such as a ChatGPT/Codex subscription connected with `pw ai codex connect`) appear under the `me:` owner, for example `me:personal/gpt-5.2-codex`.
- **Organization providers** use the `org:` owner (for example `org:openai/gpt-5.2`) and require a [budget allocation](#allocations).
An ID passed to `pw code` must contain a `/`; anything else is rejected as an invalid model format.
## Discovering Models
List every model available to you across all configured providers:
```bash
pw ai models ls
# As JSON, for scripting
pw ai models ls -o json
```
### The Interactive Model Picker
If you start `pw code` without specifying a model, the model picker opens automatically. You can also open it any time in a session by running `/model` with no arguments, or from the **Model** row in `/settings`.
In the picker:
- **Grouped by provider**: each row shows the friendly name and the full model ID.
- **Type to filter**: the list narrows as you type, matching against both the model ID and its display name.
- **Select or dismiss**: Enter selects the highlighted model; Esc first clears an active filter, then closes the picker.
- **Refresh**: Ctrl+R refreshes the list from the platform; the fetched list is cached for the rest of the session.
## Switching Models In-Session
Use the `/model` slash command:
```text
# Open the interactive picker
/model
# Switch directly to a specific model
/model Jake.Thayne:openai/gpt-5.2
```
The new model applies to all subsequent turns in the conversation.
### Which Choices Persist
- A model chosen **from the picker** is saved as your default and is used the next time you start `pw code` without specifying a model.
- A model set by typing `/model ` applies to the **current session only**.
- Allocation choices persist either way, whether picked from the allocation picker or set with `/allocation `.
- The permission mode cycled with Shift+Tab persists the same way; see [Permissions](/docs/ai/code/permissions).
Defaults are stored in your `pw code` settings and can also be set per project. See [Settings](/docs/ai/code/settings).
## Allocations
Models from organization providers (`org:` IDs) draw their spend from a **budget allocation**. Personal provider models do not use allocations.
On the command line, pass the allocation name with the `--allocation` flag:
```bash
pw code --allocation PW-QA-TEST org:openai/gpt-5.2
```
### Choosing an Allocation Interactively
In an interactive session, you never have to know the allocation name up front. When you select an organization model (or send a message with one active) and no allocation is set, `pw code` fetches the allocations you are permitted to use and prompts you to pick one. Each row shows the allocation's spend so far against its total budget. You can also open the picker at any time with `/allocation`, or change it directly with `/allocation `.
If no allocations are available to you, `pw code` reports it and asks you to contact your organization admin for access.
### Allocations in One-Shot Runs
A [one-shot (non-interactive) run](/docs/ai/code/non-interactive) cannot open a picker, so an organization model without `--allocation` fails immediately:
```text
an allocation is required for org provider models. Use --allocation to specify one.
Run 'pw code' without --prompt to browse available allocations interactively.
```
## Using a Personal ChatGPT/Codex Subscription
You can connect a personal ChatGPT/Codex subscription as an AI provider and use its models in `pw code`:
```bash
pw ai codex connect --name personal
```
This starts a device-code sign-in: open the printed URL, enter the code, and authorize. Once connected, the subscription's models become available as `me:personal/`, and usage draws on the subscription's own quota rather than a platform budget.
- **Reconnect**: `--reconnect` re-authorizes an existing provider without changing its identity.
- **Quota**: check the subscription's usage windows from inside a session with [`/usage`](/docs/ai/code/usage-and-costs).
For other provider types and sharing options, see [AI Providers](/docs/ai/ai-providers).
## Tool Calling Support
Not every model endpoint implements a tool-calling API, and `pw code` needs tool calling to read files, run commands, and edit your workspace. The gateway advertises each model as `native`, `emulated`, or `none`, shown in the "Tool calling" column of `pw ai models ls`:
- **native**: the provider's own tool-calling API is used.
- **emulated**: the provider has no tools API, so the gateway carries the tool contract in the prompt and reconstructs tool calls from the model's reply. The status line shows `emulated tools`. Tools work normally; responses are not streamed incrementally and cost more input tokens per turn.
- **none**: tool calling is unavailable. The status line shows `tools unavailable` and the session is chat-only.
See [Tool Calling & Emulation](/docs/ai/ai-providers/tool-calling) for the full mechanism and its limits.
## Default Model for Subagents
Delegated subagent tasks can run on a different default model than your session, which is useful for pointing mechanical background work at a cheaper or faster model. Set it via the **Subagent model** row in `/settings` (the `subagentModel` setting); leave it empty to have subagents inherit the session's model. See [Subagents](/docs/ai/code/subagents) for the full model resolution rules.
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Settings](/docs/ai/code/settings): Where defaults are stored
- [Slash Commands](/docs/ai/code/slash-commands): `/model`, `/allocation`, and more
- [Non-Interactive Mode](/docs/ai/code/non-interactive): Model and allocation flags in scripts
- [Subagents](/docs/ai/code/subagents): Subagent model resolution
- [Usage & Costs](/docs/ai/code/usage-and-costs): Cost estimates and provider quotas
- [AI Providers](/docs/ai/ai-providers): Configure AI providers
- [Tool Calling & Emulation](/docs/ai/ai-providers/tool-calling): What `emulated tools` in the status line means
# Non-Interactive Mode
> Source: https://parallelworks.com/docs/ai/code/non-interactive
# Non-Interactive Mode
With the `-p` (`--prompt`) flag, `pw code` runs a single prompt to completion and exits (these docs also call this a one-shot run): no full-screen interface, no follow-up questions. This is the mode to use in scripts, CI jobs, and anywhere you want the agent's answer as program output.
```bash
pw code -p "find all TODO comments" owner:provider-name/model-name
```
A model is required in one-shot mode. Pass it as the positional argument or with `-m`. Organization provider models also require [`--allocation`](/docs/ai/code/models#allocations) (there is no picker to fall back to). List available model IDs with `pw ai models ls`.
Press Ctrl+C to cancel a run in flight.
## What Goes to stdout vs. stderr
In the default text output, the streams are separated so the result stays clean:
- **stdout** carries only the model's answer, streamed as it is generated.
- **stderr** carries everything else: tool activity as it happens (a `● ToolName(...)` line per call with a condensed result line beneath it), the final usage summary, and the session/resume hint.
That means command substitution and pipes capture just the answer:
```bash
RESULT=$(pw code -p "summarize the changes in HEAD in one sentence" owner:provider-name/model-name)
echo "$RESULT"
```
Add `2>/dev/null` to silence the progress output entirely, or `2>progress.log` to keep it. Progress lines are colorized only when stderr is a terminal, so redirected logs never contain escape codes.
## JSON Output
Pass `-o json` to get a single structured result object on stdout instead of streamed text (no progress is printed for the answer itself in this mode):
```bash
pw code -p "list the Go files in this repo" -o json owner:provider-name/model-name
```
```json
{
"message": "The repository contains ...",
"model": "owner:provider-name/model-name",
"session_id": "20260719-153045-a1b2c3d4",
"iterations": 4,
"usage": {
"input_tokens": 18000,
"output_tokens": 1200,
"total_tokens": 19200
},
"estimated_cost": "$0.0480"
}
```
| Field | Description |
| --- | --- |
| `message` | The model's final answer. |
| `model` | The model ID the run used. |
| `session_id` | The local session ID, usable with `pw code -r`. |
| `iterations` | How many model requests the agent loop made to finish the prompt. |
| `usage.input_tokens` | Total input (prompt) tokens across the run. |
| `usage.output_tokens` | Total output (completion) tokens across the run. |
| `usage.total_tokens` | Input plus output tokens. |
| `estimated_cost` | Estimated cost as a dollar string, e.g. `"$0.0480"`, based on platform-configured model rates. |
Extract fields with `jq`:
```bash
pw code -p "how many source files are in src/?" -o json owner:provider-name/model-name \
| jq -r '.message, .estimated_cost'
```
## Permissions in One-Shot Runs
One-shot runs use the same [permission modes](/docs/ai/code/permissions) as interactive sessions, but there is no one to answer a prompt: any action that would normally ask for approval is **denied automatically** (it fails closed). The agent sees the denial and continues, working around the restriction or reporting it in its answer.
The same applies to workspace configuration: a one-shot run never prompts to approve a workspace's settings, MCP servers, commands, or agent definitions, so unapproved files are ignored with a notice on stderr. Launch `pw code` interactively once to approve them. See [Workspace Trust](/docs/ai/code/settings#workspace-trust).
For scripting, that means:
- `--permission-mode read-only` is the safe choice for analysis and question-answering runs.
- The default `accept-edits` mode auto-approves file edits inside the workspace, but shell commands that would normally prompt are denied unless pre-approved.
- `--allowedTools` pre-approves specific tools or commands, e.g. `--allowedTools 'Bash(git status:*)',ReadFile`.
- `--permission-mode bypass-permissions` runs every tool without prompting.
:::warning bypass-permissions runs everything
`bypass-permissions` gives the agent unrestricted tool access, including arbitrary shell commands. Use it only in environments where that is acceptable, such as a disposable CI container.
:::
## Subagents in One-Shot Runs
The agent may delegate parts of the prompt to [subagents](/docs/ai/code/subagents). In non-interactive mode, subagents always run **inline**: requests to run a task in the background are forced to block until the task finishes, so no work is lost when the process exits.
- Progress on stderr is coarse: one `● Task(...)`-style start line naming the subagent and its task, and one condensed result line when it completes. The subagent's individual tool calls are not streamed.
- Permission-gated commands a subagent runs fail closed, just like the main agent's.
- The JSON output contains only aggregate usage: subagent tokens and cost roll up into the run's `usage` and `estimated_cost` totals, and there is no per-subagent breakdown field.
## Resuming a One-Shot Session
Every one-shot run is saved as a local session. In text mode, stderr ends with the session ID and a ready-to-run resume command:
```text
Session: 20260719-153045-a1b2c3d4
Resume: pw code -r 20260719-153045-a1b2c3d4 -m owner:provider-name/model-name
```
Run that command to reopen the conversation interactively, with the one-shot exchange as history. The reverse also works: combine `-r` with `-p` to continue a saved session with another non-interactive prompt, or use `-r latest` for the most recent session. See [Sessions & Resume](/docs/ai/code/sessions).
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Permissions](/docs/ai/code/permissions): Permission modes and allow rules
- [Models & Allocations](/docs/ai/code/models): Model IDs and the `--allocation` flag
- [Sessions & Resume](/docs/ai/code/sessions): Resuming one-shot sessions
- [Subagents](/docs/ai/code/subagents): How delegated tasks behave
- [Usage & Costs](/docs/ai/code/usage-and-costs): What the usage and cost figures mean
- [pw code command reference](/docs/cli/pw/code): Full CLI reference
# Permissions
> Source: https://parallelworks.com/docs/ai/code/permissions
# Permissions
`pw code` decides what it may do on its own and what needs your approval through three layers: a **permission mode** that sets the overall level of autonomy, **allow rules** that pre-approve specific tools and commands, and a **workspace boundary** that keeps file access inside the directory you started in.
## Permission Modes
A session runs in one of four modes. The default is `accept-edits`. Each mode sets what the agent may do across reads, file edits, shell commands, and MCP tools (tools from connected [MCP servers](/docs/ai/code/mcp)).
| Mode | Reads & searches | File edits | Shell commands | MCP tools |
| --- | --- | --- | --- | --- |
| `read-only` | Allowed | Denied | Denied | Denied |
| `accept-edits` (default) | Allowed | Allowed | Prompt each time | Prompt each time |
| `plan` | Allowed | Plan files only | Denied | Denied |
| `bypass-permissions` | Allowed | Allowed | Allowed | Allowed |
[Allow rules](#allow-rules) skip the prompt in every mode except `plan`: an allowlisted command runs without asking even in `read-only` mode.
:::warning bypass-permissions runs everything
In `bypass-permissions` mode every tool call executes without prompting, including shell commands and file access outside the workspace. Use it only where that is acceptable, such as disposable environments or automation.
:::
### Plan Mode
Plan mode lets the agent work out an approach before touching anything. Reads, searches, and web fetches are allowed, but file edits are restricted to plan documents (`PLAN.md`, `plan.md`, or Markdown files inside a `plans/` directory), and shell commands are always denied, even when an allow rule matches them.
## Setting the Mode
- **At startup**: pass the `--permission-mode` flag:
```bash
pw code --permission-mode read-only
```
- **During a session**: press Shift+Tab to cycle `read-only` → `accept-edits` → `bypass-permissions` → `plan`. The status line below the composer shows the current mode, and you can cycle it even while the agent is working. The new mode applies to its next tool call.
- **In the settings menu**: run `/settings` and activate the **Permission mode** row, which cycles through the same order.
- **In your settings file**: set the `permissionMode` key. See [Settings](/docs/ai/code/settings).
Mode changes made with Shift+Tab or `/settings` are saved as your default for future sessions. The `--permission-mode` flag overrides the saved setting for that run.
## Approval Prompts
In the default `accept-edits` mode the agent reads and edits workspace files freely but stops before every shell command and MCP tool call that no allow rule covers. The prompt shows the exact command and why it needs approval, with four choices:
- **Yes, allow this command**: run it once. The next command prompts again.
- **Yes, and allow this directory for the session**: run it and remember the directories it touches, so later operations on those locations (such as access outside the workspace) do not prompt again this session.
- **No, deny this command**: skip it. The agent is told the command was denied.
- **No, and provide feedback to the agent**: deny it and type an explanation the agent can act on.
Pressing Esc also denies the command. Approval is per command: approving one shell command does not approve the next one. To stop a recurring prompt, add an allow rule instead.
Commands the CLI classifies as destructive (for example `rm -rf`, `git reset --hard`, or a force push) prompt for confirmation in every mode except `bypass-permissions`.
In [non-interactive mode](/docs/ai/code/non-interactive) there is no way to prompt, so actions that would require confirmation fail instead. Pre-approve them with allow rules, `--add-dir`, or `--permission-mode bypass-permissions`.
## Allow Rules
Allow rules pre-approve specific tool calls so they never prompt. Manage them from inside a session with `/permissions`:
```text
/permissions # list the rules in effect
/permissions add Bash(git status:*) # add a rule
/permissions remove Bash(git status:*)
/permissions remove 2 # or remove by its number from the list
```
Rules added with `/permissions add` take effect immediately and are saved to your user-level settings, so they persist across sessions. Rules that came from project settings or the command line can only be removed for the current session.
You can also pass rules at startup with the repeatable `--allowedTools` flag, or store them under the `allowedTools` key in [settings](/docs/ai/code/settings). Rules from settings files and the flag are combined:
```bash
pw code --allowedTools 'ReadFile' --allowedTools 'Bash(git status:*)'
```
### Rule Syntax
| Rule | Effect |
| --- | --- |
| `ReadFile` | A bare tool name allows every call of that tool. |
| `Bash(git status:*)` | The `:*` suffix allows a command prefix with any arguments: here `git status` alone or followed by anything. |
| `ReadFile(/data/**)` | The `/**` suffix matches a directory and everything under it. Path-scoped rules on file tools also grant access outside the workspace. |
For shell commands, every part of a compound command must match a rule: `git status && curl example.com` only runs unprompted if both `git status` and `curl example.com` are allowlisted. Commands containing command substitution (`$(...)` or backticks) are never auto-approved.
A bare tool rule such as `ReadFile` suppresses prompts for normal calls but does not widen the tool's reach: reads outside the workspace still require a path-scoped rule, `--add-dir`, or your approval.
## Workspace Boundary
The agent works within your workspace: the directory you start `pw code` in, or the one passed with `--workspace`. Paths are fully resolved before they are checked, so symlinks cannot escape the boundary.
When the agent tries to read or write a file outside the workspace, it asks first. Choosing **Yes, and allow this directory for the session** whitelists that file's directory, so further access there does not prompt again. To grant access up front:
- `--add-dir ` (repeatable) approves directories for outside-workspace reads for the whole session.
- Path-scoped allow rules such as `ReadFile(/data/**)` or `WriteFile(/tmp/**)` grant persistent access.
```bash
pw code --add-dir /data --add-dir /shared/results
```
In `bypass-permissions` mode, outside-workspace access is allowed without prompting.
Commands you type yourself in [shell mode](/docs/ai/code/interface#shell-mode) (the `!` prefix) run outside the agent's permission system entirely.
## Subagents and Permissions
- **Inherited at spawn**: subagents get the session's permission mode, allow rules, and `--add-dir` directories.
- **Live changes reach them**: changing the session's mode (for example with Shift+Tab) applies to running subagents immediately, in both directions.
- **Definitions only narrow**: a [custom agent](/docs/ai/code/custom-agents) definition can restrict a subagent's mode or tools but never widen them past the session; see [Permission Clamping](/docs/ai/code/custom-agents#permission-clamping-for-definition-authors) for the exact rules.
- **Approvals stay per-subagent**: an approval prompt names the agent asking, and what you approve applies to that subagent only. Cycling the mode inside a subagent's window adjusts that subagent alone, still capped by the session.
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Settings](/docs/ai/code/settings): The `permissionMode` and `allowedTools` keys
- [Slash Commands](/docs/ai/code/slash-commands): `/permissions` and other in-session commands
- [Non-Interactive Mode](/docs/ai/code/non-interactive): How approvals behave in one-shot runs
- [Subagents](/docs/ai/code/subagents): Delegated tasks and inherited permissions
- [Custom Agents](/docs/ai/code/custom-agents): Narrowing permissions per agent
- [MCP Servers](/docs/ai/code/mcp): How MCP tools are configured and approved
- [Interface & Shortcuts](/docs/ai/code/interface): Keyboard shortcuts including Shift+Tab
# Project Instructions
> Source: https://parallelworks.com/docs/ai/code/project-instructions
# Project Instructions
Project instruction files give the agent standing guidance about your codebase: how to build it, what conventions to follow, and what to avoid. `pw code` reads them automatically at the start of every session, so you do not have to repeat the same context in each conversation.
## How Files Are Discovered
`pw code` looks for a file named `AGENTS.md` in each directory from the root of your git repository down to the directory you launched the session in, and includes every file it finds. This means:
- Repository-wide guidance lives in an `AGENTS.md` at the repo root.
- A subproject (for example, a package in a monorepo) can add its own `AGENTS.md` with more specific instructions; both files are included when you work inside it.
- Outside a git repository, only the launch directory is checked.
For example, starting `pw code` in `packages/api/` of a repository laid out like this:
```text
repo/
AGENTS.md <- included (repository root)
packages/
api/
AGENTS.md <- included (launch directory)
web/
AGENTS.md <- not included (outside the path)
```
includes the root file and the `packages/api` file, in that order. Only directories on the path from the repo root to where you launched are checked, and at most one instruction file is read per directory.
### Overriding a Shared File
If a directory contains both `AGENTS.md` and `AGENTS.override.md`, only `AGENTS.override.md` is used: it replaces, rather than adds to, the `AGENTS.md` beside it. This is useful for keeping personal, machine-specific instructions out of a file your team shares: add `AGENTS.override.md` to your `.gitignore` and put your local variant there.
:::note Size limit
The combined instruction content is capped at 32 KB. Anything beyond the cap is truncated, so keep instruction files short and high-signal.
:::
## What to Put in Them
Instruction files are plain markdown. The most useful content is what the agent cannot discover quickly on its own:
- **Build and test commands**: the exact commands to compile, lint, and run tests
- **Conventions**: naming, formatting, and structural rules the codebase follows
- **Warnings**: generated files that must not be hand-edited, fragile areas, and required workflows
A short, specific file beats a long general one. For example:
```markdown
# Project Notes
## Commands
- Build: `make build`
- Test: `make test` (unit) or `make test-integration` (needs Docker)
- Lint: `make lint` -- run before every commit
## Conventions
- Go code follows the standard library style; wrap errors with `fmt.Errorf("...: %w", err)`.
- API handlers live in `internal/api/`; one file per resource.
## Warnings
- Files under `gen/` are generated -- edit the `.proto` sources instead.
- The base branch is `develop`, not `main`.
```
## Compatibility with Other Tools
`AGENTS.md` is a cross-tool convention, and `pw code` reads it as plain markdown with no special frontmatter, markers, or required sections. If your repository already carries an `AGENTS.md` for another coding agent, `pw code` picks it up as-is. There is nothing extra to add.
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Slash Commands](/docs/ai/code/slash-commands): Built-in and custom commands, including reusable prompt files
- [Settings](/docs/ai/code/settings): Configure pw code per workspace or globally
- [Permissions](/docs/ai/code/permissions): Control what the agent can do
# Sessions & Resume
> Source: https://parallelworks.com/docs/ai/code/sessions
# Sessions & Resume
Every `pw code` run creates a local session (a transcript of your conversation, the model used, and the workspace it ran in) stored on your machine. You can leave a session at any time and pick the conversation back up later, with the full history restored.
## How Sessions Are Saved
Sessions are saved as one file per session under `~/.local/state/pw/code-sessions` (the location respects `XDG_STATE_HOME` if set). Session IDs encode the start time plus a random suffix, for example `20260719-153045-a1b2c3d4`.
A session in which you never sent a message is not listed and cannot be resumed, so launching `pw code` and quitting immediately leaves nothing behind.
## Resuming a Session
```bash
# Resume the most recent session
pw code -r latest
# Resume a specific session by ID
pw code -r 20260719-153045-a1b2c3d4
# Pick a session from an interactive list
pw code --resume
```
If you do not specify a model when resuming, the session's original model is used. When you exit an interactive session, `pw code` prints the exact command to resume that conversation.
### The Session Picker
Running `pw code --resume` with no session ID opens an interactive picker listing your saved sessions, newest first. You can also open it from inside a running session with the `/resume` slash command.
In the picker you can:
- **Filter as you type**: The search box matches against a session's name, its first message, and its workspace path.
- **Toggle scope**: By default only sessions from the current directory are shown; switch **Scope** to **All** to see every saved session.
- **Change sort order**: Sort by last-updated (default) or creation time.
- **Preview a session**: Press Ctrl+T to view the selected session's full history, rendered as it would appear on resume, before committing to it. Scroll with the arrow keys; press Enter to resume or Esc to go back to the list.
- **Expand details**: Press Ctrl+E to show the selected session's workspace, model, timestamps, and message count.
- **Toggle density**: Press Ctrl+O to switch between compact and comfortable row spacing.
Press Enter to resume the highlighted session, or Esc to leave the picker without resuming.
### Naming Sessions
Inside a session, use `/rename ` to give it a label. Named sessions show their name in the picker, which makes long-running work easier to find than a first-message preview.
## Resuming After a One-Shot Run
One-shot (non-interactive) runs are saved as sessions too, and print a ready-to-run resume command when they finish. The reverse also works: combine `-r` with `-p` to continue any saved session non-interactively. See [Resuming a One-Shot Session](/docs/ai/code/non-interactive#resuming-a-one-shot-session).
## Session Retention
Sessions are kept forever by default. Sweeping is opt-in: set the `sessionRetentionDays` setting to a positive number, and each time `pw code` starts, session transcripts that have not been touched within that many days are deleted.
| Value | Behavior |
| --- | --- |
| `0` (or unset, or any negative value) | Sessions are kept forever (the default) |
| A positive number | Sessions untouched for that many days are deleted at startup |
The session you are currently resuming is never swept, and resuming a session restarts its retention clock. The window can also be changed from the **Session retention** row in `/settings`. See [Settings](/docs/ai/code/settings) for where to configure `sessionRetentionDays`.
:::note Subagent transcripts
Transcripts of [subagents](/docs/ai/code/subagents) are stored alongside their parent session and share its lifetime: they are cleaned up with the parent and revived together with it when you resume.
:::
## Local Sessions vs Account Chats
`pw code` sessions live only on your machine. They are not saved to your account and do not appear in the web [Chat](/docs/ai/chat) list. Chats saved to your account are managed separately; the [pw code overview](/docs/ai/code) lists the `pw ai chats` commands.
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Non-Interactive Mode](/docs/ai/code/non-interactive): One-shot prompts and JSON output
- [Slash Commands](/docs/ai/code/slash-commands): In-session commands like `/resume` and `/rename`
- [Settings](/docs/ai/code/settings): Configure `sessionRetentionDays` and other options
- [Subagents](/docs/ai/code/subagents): Parallel task delegation
- [Interface & Shortcuts](/docs/ai/code/interface): The terminal interface
- [pw code command reference](/docs/cli/pw/code): Full CLI reference
# Settings
> Source: https://parallelworks.com/docs/ai/code/settings
# Settings
`pw code` reads its configuration from a global settings file in your home directory, with optional per-workspace files you can check into a project. Common settings can also be changed from inside a session with the interactive `/settings` menu.
## Settings Files
Settings are merged from four places, in order, with later files overriding earlier ones key by key:
1. `~/.config/pw/code.json`: your global settings.
2. `/.mcp.json`: MCP servers in the cross-tool standard format.
3. `/.agents/settings.json`: project settings, typically checked in.
4. `/.agents/settings.local.json`: personal overrides for one workspace, not meant to be checked in.
All four files accept the same JSON keys. The global path honors `XDG_CONFIG_HOME` and is the same on macOS and Linux. A `mcpServers` map is replaced wholesale, not merged: the highest-precedence file that defines it supplies the entire server set. See [MCP Servers](/docs/ai/code/mcp).
## Workspace Trust
Workspace configuration only applies after you approve it. The first time `pw code` starts in a workspace whose configuration files it has not seen before, it lists them and asks whether to apply them. The gate covers everything a workspace can contribute: settings files, `.mcp.json` [MCP servers](/docs/ai/code/mcp), and the `.agents` [agent definitions](/docs/ai/code/custom-agents) and [custom commands](/docs/ai/code/slash-commands).
Your answer is remembered for that exact content: if any of the files change, you are asked again at the next launch. Until you approve, none of the workspace files apply and the session runs on your global settings alone.
[Non-interactive runs](/docs/ai/code/non-interactive) never prompt. Unapproved workspace configuration is ignored with a notice on stderr, so launch `pw code` interactively once in a workspace you want scripts to use. Approvals are stored in your global settings file under the `workspaceSettingsTrust` key, which is managed automatically.
## Key Reference
All keys are optional.
| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `model` | string | none | Model ID to start with (e.g. `Jake.Thayne:openai/gpt-5.2`). Updated automatically to the model you last used. |
| `allocation` | string | none | Budget allocation for `org:` provider models. Updated to the one you last used. |
| `permissionMode` | string | `accept-edits` | Startup [permission mode](/docs/ai/code/permissions): `read-only`, `accept-edits`, `bypass-permissions`, or `plan`. |
| `allowedTools` | string[] | `[]` | [Allow rules](/docs/ai/code/permissions) that pre-approve tool calls, e.g. `"Bash(git status:*)"`. |
| `maxTurnTokens` | number | `0` | Per-turn token budget; the turn stops when it is exceeded. `0` = unlimited. See [Usage & Costs](/docs/ai/code/usage-and-costs). |
| `compactAt` | number | `0` | Live context size, in tokens, at which the conversation is automatically compacted. `0` = default (100,000). See [Usage & Costs](/docs/ai/code/usage-and-costs). |
| `includeCoAuthoredBy` | boolean | `true` | Attribution on commits and pull requests the agent creates. See [below](#commit-and-pr-attribution). |
| `mcpServers` | object | `{}` | [MCP server](/docs/ai/code/mcp) definitions. |
| `autoScroll` | boolean | `true` | Keep the transcript pinned to the bottom as output streams. |
| `reduceMotion` | boolean | `false` | Disable the working-spinner animation. |
| `mouseClicks` | boolean | `false` | Let mouse clicks act on the interface (select picker rows, toggle blocks, drag-select). Wheel scrolling always works. |
| `sessionRetentionDays` | number | `0` | A positive number sweeps sessions untouched for that many days at startup; resuming a session resets its clock. `0` (the default) or a negative value keeps sessions forever. See [Sessions & Resume](/docs/ai/code/sessions). |
| `disableSubagents` | boolean | `false` | Withhold the delegation tool entirely, so the agent cannot spawn [subagents](/docs/ai/code/subagents). |
| `subagentConcurrency` | number | `0` | How many subagent tasks may run at once. `0` = default (10). |
| `subagentDepth` | number | `0` | How deep subagents may nest. `0` or `1` = subagents cannot spawn their own subagents. |
| `subagentModel` | string | none | Default model for delegated tasks. Empty = inherit the session's model. |
For what the subagent keys control in practice, see [Subagents](/docs/ai/code/subagents).
## Example
```json
{
"model": "Jake.Thayne:openai/gpt-5.2",
"permissionMode": "accept-edits",
"allowedTools": ["Bash(git status:*)", "Bash(go test:*)"],
"compactAt": 80000,
"includeCoAuthoredBy": false,
"sessionRetentionDays": 90,
"subagentConcurrency": 4,
"subagentModel": "Jake.Thayne:openai/gpt-5.2-mini",
"mcpServers": {
"docs": {
"command": "npx",
"args": ["-y", "docs-mcp-server"]
}
}
}
```
## The /settings Menu
Run `/settings` in an interactive session to change the most common settings without editing files. Type to filter the rows, move with the arrow keys, and press Enter to change the highlighted row; Esc closes the menu. Changes are saved to your global settings immediately.
| Row | What it does |
| --- | --- |
| **Permission mode** | Cycles `read-only` → `accept-edits` → `bypass-permissions` → `plan`. See [Permissions](/docs/ai/code/permissions). |
| **Co-authored-by trailer** | Toggles commit and pull request attribution on or off. |
| **Auto-scroll** | Toggles following the transcript as output streams. |
| **Reduce motion** | Toggles the working-spinner animation. |
| **Mouse clicks** | Toggles click interaction with the interface; scrolling and text selection always work. |
| **Subagents** | Enables or disables delegating tasks to subagents. |
| **Subagent concurrency** | Opens a number box for the parallel-task limit. Enter applies, Esc cancels; leaving it empty keeps the current value. |
| **Subagent nesting depth** | Opens a number box; `1` means subagents cannot spawn their own subagents. |
| **Subagent model** | Opens a model picker for the default delegated-task model. Shows `(inherit session)` when unset. |
| **Session retention** | Opens a number box for the sweep window in days; `0` keeps sessions forever. See [Sessions & Resume](/docs/ai/code/sessions). |
| **Model** | Opens the model picker to change the session's model. |
| **Allocation** | Opens the allocation picker (org providers). See [Models & Allocations](/docs/ai/code/models). |
## Commit and PR Attribution
When `includeCoAuthoredBy` is enabled (the default), the agent ends every commit message it creates with an attribution line and a `Co-Authored-By: pw code ` trailer, and ends the pull requests it opens with the same attribution line. Turning it off with the **Co-authored-by trailer** row in `/settings` applies to the current session's future commits, not just the next launch.
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Permissions](/docs/ai/code/permissions): Permission modes and allow rules
- [MCP Servers](/docs/ai/code/mcp): The `mcpServers` key and `.mcp.json`
- [Subagents](/docs/ai/code/subagents): Behavior behind the subagent keys
- [Models & Allocations](/docs/ai/code/models): Model IDs and budget allocations
- [Sessions & Resume](/docs/ai/code/sessions): Session storage and retention
- [Slash Commands](/docs/ai/code/slash-commands): `/settings` and other in-session commands
# Slash Commands
> Source: https://parallelworks.com/docs/ai/code/slash-commands
# Slash Commands
Slash commands let you control a `pw code` session without leaving the conversation. Type `/` in the composer to open the command palette, which filters as you type, or run `/help` in a session to print the same list. Press Enter to run the highlighted command.
## Built-In Commands
| Command | Description |
| --- | --- |
| [`/allocation [allocation-name]`](/docs/ai/code/models#allocations) | Show or change the budget allocation (org providers only) |
| [`/auth`](/docs/ai/code/troubleshooting#authentication-expired-mid-session) | Re-authenticate when your token or API key has expired |
| `/clear` | Clear conversation and start fresh |
| [`/compact`](/docs/ai/code/usage-and-costs#context-compaction) | Manually compact conversation history |
| [`/cost`](/docs/ai/code/usage-and-costs) | Show token usage and estimated cost |
| `/diff` | Show git diff for workspace |
| [`/fork `](/docs/ai/code/subagents#forking-the-conversation) | Fork this conversation into a subagent with its full history |
| `/help` | Show available commands |
| [`/mcp`](/docs/ai/code/mcp) | Show MCP server connection status and tools |
| [`/model [model-name]`](/docs/ai/code/models) | Show or change the current model |
| [`/permissions [add\|remove ]`](/docs/ai/code/permissions#allow-rules) | View and manage allowed tool rules |
| [`/rename `](/docs/ai/code/sessions) | Rename the current session |
| [`/resume`](/docs/ai/code/sessions) | Resume a previous session from a picker |
| [`/settings`](/docs/ai/code/settings#the-settings-menu) | Change pw code settings |
| `/status` | Show session status |
| [`/usage`](/docs/ai/code/usage-and-costs#provider-quotas-usage) | Show provider usage and reset times |
| `/version` | Show CLI version |
:::note /usage availability
`/usage` only appears in the palette and in `/help` when the selected model's provider reports usage information. If your provider does not expose usage windows, the command is hidden.
:::
`/fork` hands a task to a subagent that starts with a full copy of the conversation so far. See [Subagents](/docs/ai/code/subagents) for details.
The composer has two other prefixes: `@` references files and `!` runs a shell command yourself. See [Interface & Shortcuts](/docs/ai/code/interface).
## Custom Slash Commands
You can define your own slash commands as markdown files. A file named `.md` becomes the command `/name`, and its body is the prompt sent to the agent when you run it.
`pw code` looks for command files in these locations, in order of precedence:
1. `/.agents/commands/`: project commands, shared with your team through version control
2. `~/.config/agents/commands/`: personal commands, available in every workspace (respects `XDG_CONFIG_HOME`)
When the same command name exists in both locations, the project file wins.
:::note Project commands require approval
Command files in the workspace are part of the configuration `pw code` asks you to approve at launch. See [Workspace Trust](/docs/ai/code/settings#workspace-trust).
:::
### File Format
An optional frontmatter block sets how the command appears in the palette:
- `description`: the one-line description shown next to the command
- `argument-hint`: appended to the command name in the palette to show what arguments it expects
The body is a prompt template. These placeholders are substituted when the command runs:
- `$ARGUMENTS` (or `$ARGS`): everything typed after the command name
- `$1` through `$9`: individual space-separated arguments; a position with no argument expands to nothing
### Example
Save this as `.agents/commands/fix-issue.md` in your workspace:
```markdown
---
description: Investigate and fix a GitHub issue
argument-hint:
---
Look up GitHub issue #$1 with `gh issue view $1`.
Reproduce the problem, implement a fix, and run the relevant tests.
Summarize the root cause when you are done.
```
Then run it from the composer:
```text
/fix-issue 123
```
The agent receives the body with `$1` replaced by `123` and works through it as a normal turn.
:::info MCP prompts are slash commands too
Connected MCP servers can expose prompt templates, which appear in the palette as `/mcp____`. See [MCP Servers](/docs/ai/code/mcp) for how arguments are passed.
:::
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Subagents](/docs/ai/code/subagents): Fork conversations and delegate tasks
- [MCP Servers](/docs/ai/code/mcp): Connect external tools and prompts
- [Permissions](/docs/ai/code/permissions): Permission modes and allow rules
- [Sessions & Resume](/docs/ai/code/sessions): Save, rename, and resume sessions
- [Usage & Costs](/docs/ai/code/usage-and-costs): Track token usage and spend
- [Settings](/docs/ai/code/settings): Configure `pw code`
- [Interface & Shortcuts](/docs/ai/code/interface): Keyboard shortcuts and the composer
# Subagents
> Source: https://parallelworks.com/docs/ai/code/subagents
# Subagents
`pw code` can split work across subagents: helper agents that each run their own agent loop and report back. When a request contains independent pieces (a broad search, a refactor across many files, a research question), the agent can delegate each piece to a subagent instead of doing everything itself, and independent pieces run at the same time.
Each subagent:
- **Starts with a fresh context**: it sees none of your conversation, so the agent hands it a self-contained brief.
- **Works in the same directory**: it shares your working tree and your MCP tools, so its edits land in the same files you are looking at. (Custom agent types can opt into an isolated worktree instead; see [Custom Agents](/docs/ai/code/custom-agents).)
- **Reports back a summary**: when it finishes, its report is delivered into the main conversation.
The agent decides when delegating is worthwhile, and you can also ask for it directly: "delegate these three fixes to subagents" or "research this in the background while we keep working." This page covers how delegation behaves, the agent switcher, follow-ups, forks, models, persistence, and limits.
## Background and Inline Delegation
- **Background by default**: when the agent delegates, the main conversation continues immediately; the subagent works on its own. When it finishes, its report arrives in the main conversation as a completion notice. If the session is sitting idle, the arrival wakes it so the agent can act on the result without you typing anything.
- **Inline when a step depends on it**: when a later step in the same turn depends on the result, the agent waits for the subagent and receives the report directly.
- **Concurrent**: several subagents launched in one turn run in parallel, up to the concurrency limit (10 by default; more wait for a free slot).
- **Interim messages**: if a running subagent hits a load-bearing finding or a blocker mid-task, it can surface an interim message to the main conversation and keep working. The main agent can answer with direction the same way you would (see [Following Up](#following-up) below).
- **Stopping is never silent**: if you stop a subagent yourself, the main agent is told it was interrupted and returned no result; it can still be resumed later by its ID.
Whether it runs in the background or inline, every subagent has an ID like `task-2` that appears with its report and is used for follow-up work.
## The Agent Switcher
Once the session has at least one subagent, the agent switcher appears below the composer (one row per agent, starting with **main**). Each row shows a colored status dot, the agent's name, its custom agent type (when it has one), and a live activity line such as the file it is reading or `Done (...)`. The footer hints `↓ for agents`.
Press ↓ at the composer (past any input history; on a multi-line draft, with the cursor on the last line) to move the selection into the switcher. Your draft is preserved.
| Key | Action |
| --- | --- |
| ↓ / ↑ | Move the selection; moving up past the top row returns to the composer |
| Enter | View the selected agent's window (arrows keep working, so you can step through agents) |
| Esc | Leave the switcher and return to the composer |
| x | Stop the selected running agent, or dismiss a finished agent's row |
| Ctrl+X | Stop every agent and clear the switcher |
Typing any other key returns you to the composer and is handled normally.
### Viewing and Prompting a Subagent
Selecting an agent with Enter switches you into its window: its full transcript, with its own composer. Each window keeps its own half-typed draft, so switching around never loses what you were writing.
You can prompt a subagent directly from its window, including after it has finished its task, which resumes it with its conversation intact. Press Esc while viewing a running subagent to stop it.
### Task Blocks in the Transcript
In the main transcript, each delegation renders as a task block titled `Task(description)` (or the agent type's name for custom agents) with a colored dot matching the agent's switcher row. Collapsed (the default), a block shows a spinner and the latest action while running, then a one-line `Done (...)` summary:
Done (12 tool uses · 38.2K tokens)
Press Ctrl+O to expand it into the full step-by-step activity feed, and again to collapse it (clicking the block also works when mouse clicks are enabled in `/settings`).
The moment a background subagent's report reaches the conversation is also marked in the transcript, so you can see exactly when the main agent learned the result.
### Permission Prompts from Subagents
When a subagent needs approval for a permission-gated command, the prompt appears in your session and names which agent is asking. Approvals you grant this way apply to that subagent only. Changing the session's permission mode while subagents are running applies to them immediately, in both directions. A custom agent definition can narrow a subagent's permissions but never widen them; see [Permission Clamping](/docs/ai/code/custom-agents#permission-clamping-for-definition-authors).
## Following Up
Every subagent report includes the subagent's ID (for example `task-3`). The main agent can send follow-up work to that ID, and the subagent picks it up with its full context retained, so there is no need to re-explain the task. Just ask: "have the same agent also update the tests."
If the subagent is still working, the follow-up is delivered mid-task as a course correction instead, and the original task continues with the new direction applied.
Follow-ups do not count against the per-session subagent budget, and they survive restarts: see [Persistence and Resume](#persistence-and-resume).
## Forking the Conversation
`/fork ` spawns a background subagent seeded with your conversation's **full history** (everything discussed so far) and sets it to work on the task. Use it for side-work that needs all the context you have built up, without derailing the main thread:
```text
/fork write up the migration plan we just discussed as a design doc
```
- The current conversation is unaffected; the fork runs in the background in the same working tree.
- Check on it with ↓ like any other subagent; its result lands back in the main conversation, and you can follow up by its ID.
- `/fork` works from the main session only, and a fork cannot fork again.
- A fork always stays on the session's model, even when a subagent default model is set.
## Models for Subagents
By default a subagent inherits the session's model. You can point delegated work at a different model (for example a cheaper, faster model for mechanical tasks) at several levels, where later ones win:
1. **The session's model**: the baseline every subagent inherits.
2. **The subagent default**: set via `/settings` → **Subagent model** (it shows `(inherit session)` when unset) or the `subagentModel` key in `settings.json`. Applies to all delegated tasks.
3. **The agent definition's `model:` key**: a [custom agent type](/docs/ai/code/custom-agents) can name its own model.
4. **A per-delegation choice**: the agent can pick a model for one specific delegation ("use the small model for this"); that choice sticks for follow-ups to the same subagent.
Two exceptions: forks always keep the session's model, and changing the subagent default never changes the session's own model. See [Models & Allocations](/docs/ai/code/models).
## Persistence and Resume
Subagents persist with their session:
- **Stored beside the parent session**: subagent transcripts live under their parent session's storage, never as standalone sessions, so they do not appear in the session picker.
- **Revived on resume**: `pw code -r ` brings every persisted subagent back as an idle agent in the switcher, with its conversation intact. You can view it, prompt it, and the main agent can send it follow-up work by its old ID.
- **Hibernated when finished**: a finished background subagent releases its conversation from memory until you view or prompt it, so sessions with many subagents stay light.
- **Swept with the session**: if you have enabled the session retention sweep (`sessionRetentionDays`), it deletes a session's subagent transcripts along with the session. See [Sessions & Resume](/docs/ai/code/sessions).
- **Dirty worktrees survive**: an isolated worktree holding uncommitted changes or new commits is kept, and resuming the session re-adopts the subagent inside it; see [Worktree Isolation](/docs/ai/code/custom-agents#worktree-isolation).
:::note /clear starts fresh
`/clear` stops every subagent, forgets them all, and resets the per-session subagent budget. A cleared conversation never receives a stale completion from a subagent it no longer knows about.
:::
## Non-Interactive Mode
In a one-shot run (`pw code -p`), there is no later turn to deliver a background result into, so every delegation runs inline: the agent waits for each subagent, and no work is lost when the process exits. For the stderr progress format and the usage roll-up, see [Subagents in One-Shot Runs](/docs/ai/code/non-interactive#subagents-in-one-shot-runs).
## Limits and Controls
| Control | Default | Where |
| --- | --- | --- |
| Subagents on/off | on | `/settings` → **Subagents**, or `disableSubagents` in `settings.json`. Turning them off removes the delegation capability entirely |
| Concurrency | 10 at a time | `/settings` → **Subagent concurrency**, or `subagentConcurrency` (0 = default). Extra delegations wait for a free slot; changes apply live |
| Per-session budget | 200 subagents | Fixed. Once reached, the agent is told to finish the remaining work itself; `/clear` resets the budget |
| Nesting | off | `/settings` → **Subagent nesting depth**, or `subagentDepth`. `0`/`1` = subagents cannot spawn their own subagents; higher values allow deeper delegation, and nested subagents still appear in the same switcher |
Example `settings.json` excerpt:
```json
{
"subagentModel": "owner:provider-name/small-model",
"subagentConcurrency": 6,
"subagentDepth": 1,
"disableSubagents": false
}
```
See [Settings](/docs/ai/code/settings) for where settings files live.
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Custom Agents](/docs/ai/code/custom-agents): Define reusable agent types with their own tools, model, and prompt
- [Permissions](/docs/ai/code/permissions): Permission modes and approvals
- [Sessions & Resume](/docs/ai/code/sessions): Session storage, the picker, and retention
- [Settings](/docs/ai/code/settings): The `/settings` menu and `settings.json`
- [Non-Interactive Mode](/docs/ai/code/non-interactive): One-shot runs with -p
# Troubleshooting
> Source: https://parallelworks.com/docs/ai/code/troubleshooting
# Troubleshooting
Solutions to common issues when working with `pw code`. For problems with the web chat interface, see [Chat troubleshooting](/docs/ai/chat/troubleshooting).
## pw code Is Not Recognized or Lacks a Feature
**Symptom:** The `pw code` command is missing, or a feature described in these docs does not exist in your install.
**Cause:** The CLI is not installed or is outdated.
**Solution:** Check your version with `pw --version` (or `/version` inside a session) and update to the latest release. See the [CLI documentation](/docs/cli).
## No Models Available
**Symptom:** The model picker is empty, or `pw code` reports that no models are available.
**Cause:** No AI provider is configured for your account, or none is shared with you.
**Solution:**
- Run `pw ai models ls` to see the models you can use, and `pw ai providers ls` to see your providers.
- If both are empty, configure a provider or ask your administrator for access. See [AI Providers](/docs/ai/ai-providers).
- Verify you are authenticated: run `pw auth` and paste your credential when prompted.
## "An allocation is required for org provider models"
**Symptom:** Starting with an `org:` model fails with an allocation error, or a one-shot run exits immediately with this message.
**Cause:** Organization provider models draw from a budget allocation, and none is set.
**Solution:**
- In an interactive session, `pw code` prompts you to pick from the allocations you may use; you can also run `/allocation` at any time.
- In [non-interactive runs](/docs/ai/code/non-interactive) there is no picker: pass `--allocation `.
- If no allocations are listed, ask your organization admin for access. See [Models & Allocations](/docs/ai/code/models).
## Invalid Model Format
**Symptom:** `pw code ` rejects the model ID.
**Cause:** Model IDs must have the form `owner:provider-name/model-name` and always contain a `/`.
**Solution:** Run `pw ai models ls` and copy the ID exactly, for example `Jake.Thayne:openai/gpt-5.2` or `org:openai/gpt-5.2`. See [Models & Allocations](/docs/ai/code/models).
## Authentication Expired Mid-Session
**Symptom:** Requests start failing with authentication errors partway through a session.
**Cause:** Your token or API key expired while the session was open.
**Solution:** Run `/auth` inside the session to re-authenticate without losing your conversation. Credentials are entered at a secure prompt. Never paste them into the chat itself.
## The Agent Will Not Edit Files
**Symptom:** Every edit is denied, or the agent only reads and plans.
**Cause:** The session is in a restrictive [permission mode](/docs/ai/code/permissions): `read-only` denies edits, and `plan` allows edits only to plan documents.
**Solution:** Check the mode in the status line and press Shift+Tab to cycle to `accept-edits`, or restart with `--permission-mode accept-edits`. Mode changes made with Shift+Tab persist as your default.
## Shell Commands Prompt Every Time
**Symptom:** The agent stops for approval on the same command over and over.
**Cause:** Approvals are per command; nothing is remembered unless you add an allow rule.
**Solution:**
- Add a rule from inside the session: `/permissions add Bash(git status:*)`. Rules added this way persist across sessions.
- Note that every part of a compound command must be covered by a rule, and commands containing `$(...)` or backticks are never auto-approved. See [Permissions](/docs/ai/code/permissions).
## Scripted Runs Fail on Approvals
**Symptom:** A `-p` run reports that commands were denied, or does less than expected.
**Cause:** One-shot runs cannot prompt, so any action that would need approval fails closed.
**Solution:** Pre-approve what the run needs with `--allowedTools` or `--add-dir`, or choose a mode that fits the job: `read-only` for analysis, `bypass-permissions` only in disposable environments. See [Non-Interactive Mode](/docs/ai/code/non-interactive).
## "Turn stopped: per-turn token budget reached"
**Symptom:** A turn ends with this message in the transcript.
**Cause:** The `maxTurnTokens` setting caps how many tokens a single turn may consume.
**Solution:** The session continues: send the next message to pick up where the turn stopped, or raise or unset `maxTurnTokens`. See [Usage & Costs](/docs/ai/code/usage-and-costs).
## The Agent Seems to Forget Earlier Context
**Symptom:** The agent stops referencing details from earlier in a long session.
**Cause:** When the live context reaches the compaction threshold, older messages are replaced with a summary.
**Solution:** This is expected in long sessions. Re-state the constraints that matter, keep them in [project instructions](/docs/ai/code/project-instructions) so they survive compaction, or raise the threshold with the `compactAt` setting. See [Usage & Costs](/docs/ai/code/usage-and-costs).
## A Session Is Missing from the Picker
**Symptom:** `pw code --resume` does not list a session you expect.
**Cause:** The picker defaults to sessions from the current directory; sessions in which you never sent a message are not saved; and sessions may have been swept if you enabled retention.
**Solution:**
- Switch **Scope** to **All** in the picker to see every saved session.
- Sessions are kept forever unless you set `sessionRetentionDays` to a positive number, in which case sessions untouched for that many days are deleted at startup. See [Sessions & Resume](/docs/ai/code/sessions).
## Sessions Do Not Appear in the Web Chat List
**Symptom:** Sessions from `pw code` are not visible in the Chat interface.
**Cause:** This is expected: `pw code` sessions are stored locally on your machine and are never uploaded to your account.
**Solution:** Resume local sessions with `pw code -r`. Chats saved to your account are separate; manage them with `pw ai chats`. See the [pw code overview](/docs/ai/code).
## The Agent Never Delegates to Subagents
**Symptom:** Asking the agent to parallelize or delegate does nothing, and the agent switcher never appears.
**Cause:** Subagents are disabled, or the session hit its per-session subagent budget.
**Solution:**
- Check that the **Subagents** row in `/settings` is enabled (the `disableSubagents` setting).
- A session may spawn at most 200 subagents; once reached, the agent finishes work itself. `/clear` resets the budget along with the conversation. See [Subagents](/docs/ai/code/subagents).
## A Subagent's Changes Are Not in My Files
**Symptom:** A subagent reports completed edits, but your working tree is unchanged.
**Cause:** Custom agents with worktree isolation run in a temporary git worktree, a separate checkout of the repository.
**Solution:** The subagent's report names the worktree path; fetch or merge its work from there. See [Worktree Isolation](/docs/ai/code/custom-agents#worktree-isolation).
## An MCP Server's Tools Are Missing
**Symptom:** A configured MCP server never connects, or its tools are not offered to the agent.
**Cause:** The server failed to start or connect, or its configuration is shadowed by a higher-precedence file.
**Solution:**
- Run `/mcp` to see each server's status and `pw code mcp list` to see which config file is active. An `mcpServers` map in a higher-precedence file replaces the whole map below it.
- Slow servers (for example, ones that download packages on first run) may need a longer timeout: set a per-server `timeout` or the `MCP_TIMEOUT` environment variable.
- A stdio server must keep stdout clean for the protocol and log to stderr only. See [MCP Servers](/docs/ai/code/mcp).
## Workspace Settings or Commands Are Not Applying
**Symptom:** A workspace's `.agents` settings, MCP servers, custom commands, or agent definitions have no effect.
**Cause:** Workspace configuration only applies after you approve it, and unapproved files are ignored. Non-interactive runs never prompt for approval.
**Solution:** Launch `pw code` interactively in that workspace and answer the approval prompt; the approval is remembered until the files change. See [Workspace Trust](/docs/ai/code/settings#workspace-trust).
## Images Will Not Paste
**Symptom:** Ctrl+V does not attach a clipboard image, especially over SSH.
**Cause:** Inside an SSH session your local clipboard is not reachable by the remote `pw code` process.
**Solution:** Copy the file to the remote machine (for example with `scp`) and attach it by path with `@~/screenshot.png` instead. See [Interface & Shortcuts](/docs/ai/code/interface).
## Getting Help
If the solutions above do not resolve your issue:
1. Run `/status` in a session for a summary of the model, session, and configuration in effect.
2. Check the [pw code overview](/docs/ai/code) for prerequisites and setup.
3. Review [AI Providers](/docs/ai/ai-providers) to verify your provider configuration.
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Permissions](/docs/ai/code/permissions): Permission modes and allow rules
- [Models & Allocations](/docs/ai/code/models): Model IDs and budget allocations
- [Sessions & Resume](/docs/ai/code/sessions): Session storage and retention
- [Subagents](/docs/ai/code/subagents): Delegation, the switcher, and limits
- [MCP Servers](/docs/ai/code/mcp): Server configuration and connection behavior
- [Chat troubleshooting](/docs/ai/chat/troubleshooting): Issues with the web chat interface
# Usage & Costs
> Source: https://parallelworks.com/docs/ai/code/usage-and-costs
# Usage & Costs
`pw code` tracks token usage and estimated cost throughout a session, keeps long conversations within the model's context window through compaction (summarizing older messages to free context space), and lets you cap how much a single turn can consume.
## Session Usage: `/cost` and the Status Line
The status line at the bottom of the interface always shows a compact summary: the **live context size** (the tokens the model currently reads each turn), the **cumulative total** for the session, and the estimated cost once it is non-trivial, for example `98.5K ctx · 1.2M total (~$1.8402)`.
For the full breakdown, run `/cost`:
```text
Token Usage:
Input: 1.1M tokens
Output: 85.3K tokens
Turns: 42
Estimated cost: $1.8402
```
Costs are estimated from the per-token rates configured on the platform for each model, priced per model, so a session that switched models is costed against the model that produced each turn. Usage from [subagents](/docs/ai/code/subagents) rolls up into the session totals as it happens, so `/cost` reflects everything the session spent, delegated work included.
:::note Estimates depend on configured rates
Models with no configured rate, such as custom or session-tunnel providers, contribute nothing to the estimate. A session that used such a model can show a lower cost than it actually incurred.
:::
## Provider Quotas: `/usage`
Some providers report their own usage limits, most notably a connected ChatGPT/Codex subscription, which has rolling quota windows. For models from such a provider, `/usage` shows each window as a bar with its reset time:
```text
Provider usage (plus plan)
5-hour limit
[████████░░░░░░░░░░░░] 41.0% used
Resets Jul 19, 2026 at 6:00 PM CDT
Weekly limit
[██░░░░░░░░░░░░░░░░░░] 12.5% used
Resets Jul 23, 2026 at 9:00 AM CDT
```
`/usage` is only available when the selected model's provider reports usage information; otherwise the command is hidden from the palette and `/help`. This is the provider's own quota, separate from the platform cost estimate above.
## Context Compaction
As a conversation grows, every turn sends more history to the model. When the live context reaches the compaction threshold (**100,000 input tokens** by default), `pw code` automatically compacts the conversation at the end of the turn: older messages are replaced with a model-written summary, while the system prompt and the most recent messages are kept verbatim. The conversation continues seamlessly, the `ctx` figure in the status line drops, and the compaction is recorded in the [session file](/docs/ai/code/sessions) so a later resume sees the compacted history.
You can also compact manually at any time with `/compact`, which shows you the summary it produced.
The threshold is configurable with the `compactAt` setting (a token count) in your [settings](/docs/ai/code/settings):
```json
{
"compactAt": 150000
}
```
## Per-Turn Budget: `maxTurnTokens`
The `maxTurnTokens` setting caps how many tokens (input plus output) a single turn may consume across all of its model requests. When a turn reaches the budget, it stops with a message in the transcript:
```text
Turn stopped: per-turn token budget of 200000 reached.
```
The session itself continues, and you can send the next message as usual. Unset (or `0`) means no per-turn limit. This is a useful guardrail for autonomous multi-step work, where a single prompt can otherwise fan out into many tool-calling iterations.
```json
{
"maxTurnTokens": 200000
}
```
## Usage in Non-Interactive Runs
One-shot (non-interactive) runs report the same numbers. In text mode, the status-line summary is printed to stderr when the run completes; with `-o json`, the output object carries `usage.input_tokens`, `usage.output_tokens`, `usage.total_tokens`, and `estimated_cost`. See [Non-Interactive Mode](/docs/ai/code/non-interactive) for the full schema. Subagent usage is included in these totals; there is no per-subagent breakdown.
## Account-Level Usage
The estimates above are per-session. For metered spend and token reporting across your account (including Chat, AI keys, and allocation budgets), use the [AI Usage](/docs/ai/ai-usage) dashboard under **AI** > **AI Usage** in ACTIVATE. Organization admins can also see organization-wide usage there, grouped by model, user, or allocation.
## Related Documentation
- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Non-Interactive Mode](/docs/ai/code/non-interactive): Usage and cost fields in JSON output
- [Subagents](/docs/ai/code/subagents): How delegated work is counted
- [Sessions & Resume](/docs/ai/code/sessions): Where compacted history is stored
- [Settings](/docs/ai/code/settings): `compactAt`, `maxTurnTokens`, and other options
- [Models & Allocations](/docs/ai/code/models): Budget allocations for organization providers
- [AI Usage](/docs/ai/ai-usage): Account-level usage reporting
# 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: `/.pw/code/settings.json`, `settings.local.json`, and any custom commands under `/.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.
_A screenshot of provisioned buckets, displayed in a terminal as a table_
# pw
> Source: https://parallelworks.com/docs/cli/pw
## pw
The Parallel Works ACTIVATE CLI
### Synopsis
**pw** is the base for all other PW CLI commands.
Run **pw** alone to check that the PW CLI is installed and to list compatible commands.
```
pw [flags]
```
### Options
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
-h, --help help for pw
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
--version string[="release"] Print version information (release, json)
```
### SEE ALSO
* [pw ai](/docs/cli/pw/ai) - Manage AI providers, models, and chats
* [pw api](/docs/cli/pw/api) - Make an authenticated request to the ACTIVATE API
* [pw auth](/docs/cli/pw/auth) - Authenticate the CLI
* [pw billing](/docs/cli/pw/billing) - Manage billing units, SKUs, allocations, and usage
* [pw buckets](/docs/cli/pw/buckets) - Manage cloud buckets
* [pw cluster](/docs/cli/pw/cluster) - Manage clusters
* [pw code](/docs/cli/pw/code) - AI coding agent
* [pw context](/docs/cli/pw/context) - Manage CLI contexts
* [pw endpoints](/docs/cli/pw/endpoints) - Create and serve self-registering endpoint sessions
* [pw environments](/docs/cli/pw/environments) - Manage compute environments
* [pw forward](/docs/cli/pw/forward) - Forward remote ports to your local machine via SSH tunnels
* [pw groups](/docs/cli/pw/groups) - Manage groups and their members
* [pw kube](/docs/cli/pw/kube) - Kubernetes commands
* [pw lustre](/docs/cli/pw/lustre) - Manage Lustre filesystems
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
* [pw nfs](/docs/cli/pw/nfs) - Manage NFS storages
* [pw orgs](/docs/cli/pw/orgs) - Manage organizations
* [pw sessions](/docs/cli/pw/sessions) - Manage sessions
* [pw ssh](/docs/cli/pw/ssh) - Initiate an SSH connection to a resource
* [pw ssh-public-keys](/docs/cli/pw/ssh-public-keys) - Get the SSH public keys for a user
* [pw subdomains](/docs/cli/pw/subdomains) - Reserve session subdomains
* [pw upgrade](/docs/cli/pw/upgrade) - Update the version of the CLI
* [pw users](/docs/cli/pw/users) - Manage organization users
* [pw variables](/docs/cli/pw/variables) - Manage your user variables
* [pw version](/docs/cli/pw/version) - Show detailed CLI version information
* [pw vscode](/docs/cli/pw/vscode) - Open VS Code connected to a remote resource
* [pw workers](/docs/cli/pw/workers) - Manage compute workers
* [pw workflows](/docs/cli/pw/workflows) - Manage workflows
# pw ai
> Source: https://parallelworks.com/docs/cli/pw/ai
## pw ai
Manage AI providers, models, and chats
### Synopsis
The **pw ai** command group has commands for managing AI providers, chatting with models, and viewing chats.
```
pw ai [flags]
```
### Options
```
-h, --help help for ai
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw ai chats](/docs/cli/pw/ai/chats) - Manage AI chats
* [pw ai codex](/docs/cli/pw/ai/codex) - Manage ChatGPT/Codex subscription providers
* [pw ai models](/docs/cli/pw/ai/models) - Manage AI models
* [pw ai providers](/docs/cli/pw/ai/providers) - Manage AI providers
# pw ai chats
> Source: https://parallelworks.com/docs/cli/pw/ai/chats
## pw ai chats
Manage AI chats
### Synopsis
The **pw ai chats** command group has commands for listing, viewing, and deleting AI chats.
```
pw ai chats [flags]
```
### Options
```
-h, --help help for chats
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai](/docs/cli/pw/ai) - Manage AI providers, models, and chats
* [pw ai chats delete](/docs/cli/pw/ai/chats/delete) - Delete an AI chat
* [pw ai chats get](/docs/cli/pw/ai/chats/get) - Get an AI chat
* [pw ai chats ls](/docs/cli/pw/ai/chats/ls) - List AI chats
# pw ai chats delete
> Source: https://parallelworks.com/docs/cli/pw/ai/chats/delete
## pw ai chats delete
Delete an AI chat
### Synopsis
The **pw ai chats delete** command deletes a chat.
```
pw ai chats delete [flags]
```
### Examples
```
# Delete a chat
pw ai chats delete abc-123
```
### Options
```
-h, --help help for delete
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai chats](/docs/cli/pw/ai/chats) - Manage AI chats
# pw ai chats get
> Source: https://parallelworks.com/docs/cli/pw/ai/chats/get
## pw ai chats get
Get an AI chat
### Synopsis
The **pw ai chats get** command retrieves a chat and displays its messages.
```
pw ai chats get [flags]
```
### Examples
```
# View a chat
pw ai chats get abc-123
# View as JSON
pw ai chats get -o json abc-123
```
### Options
```
-h, --help help for get
-o, --output string Output format (text, json) (default "text")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai chats](/docs/cli/pw/ai/chats) - Manage AI chats
# pw ai chats ls
> Source: https://parallelworks.com/docs/cli/pw/ai/chats/ls
## pw ai chats ls
List AI chats
### Synopsis
The **pw ai chats ls** command lists your AI chats.
```
pw ai chats ls [flags]
```
### Examples
```
# List chats
pw ai chats ls
# List as JSON
pw ai chats ls -o json
# List with pagination
pw ai chats ls --limit 10 --offset 20
```
### Options
```
-h, --help help for ls
--limit int Maximum number of chats to return (default 20)
--offset int Number of chats to skip
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai chats](/docs/cli/pw/ai/chats) - Manage AI chats
# pw ai codex
> Source: https://parallelworks.com/docs/cli/pw/ai/codex
## pw ai codex
Manage ChatGPT/Codex subscription providers
### Synopsis
The **pw ai codex** command group connects one or more ChatGPT/Codex
subscriptions as personal AI providers for pw code and AI chat.
```
pw ai codex [flags]
```
### Options
```
-h, --help help for codex
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai](/docs/cli/pw/ai) - Manage AI providers, models, and chats
* [pw ai codex connect](/docs/cli/pw/ai/codex/connect) - Connect a ChatGPT/Codex subscription as a personal AI provider
# pw ai codex connect
> Source: https://parallelworks.com/docs/cli/pw/ai/codex/connect
## pw ai codex connect
Connect a ChatGPT/Codex subscription as a personal AI provider
### Synopsis
The **pw ai codex connect** command starts a ChatGPT device-code sign-in and
connects the subscription as a personal AI provider. Models become
available as **me:/** and usage draws on the subscription's quota.
```
pw ai codex connect [flags]
```
### Examples
```
# Connect a subscription as a new provider
pw ai codex connect --name personal
# Reconnect an existing provider without changing its identity
pw ai codex connect --name personal --reconnect
```
### Options
```
-h, --help help for connect
--name string Name for the AI provider
--reconnect Reconnect an existing Codex provider
-y, --yes Skip the confirmation prompt
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai codex](/docs/cli/pw/ai/codex) - Manage ChatGPT/Codex subscription providers
# pw ai models
> Source: https://parallelworks.com/docs/cli/pw/ai/models
## pw ai models
Manage AI models
### Synopsis
The **pw ai models** command group has commands for listing available AI models.
```
pw ai models [flags]
```
### Options
```
-h, --help help for models
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai](/docs/cli/pw/ai) - Manage AI providers, models, and chats
* [pw ai models ls](/docs/cli/pw/ai/models/ls) - List available AI models
# pw ai models ls
> Source: https://parallelworks.com/docs/cli/pw/ai/models/ls
## pw ai models ls
List available AI models
### Synopsis
The **pw ai models ls** command lists all AI models available across all configured providers.
```
pw ai models ls [flags]
```
### Examples
```
# List all models
pw ai models ls
# List as JSON
pw ai models ls -o json
```
### Options
```
-h, --help help for ls
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai models](/docs/cli/pw/ai/models) - Manage AI models
# pw ai providers
> Source: https://parallelworks.com/docs/cli/pw/ai/providers
## pw ai providers
Manage AI providers
### Synopsis
The **pw ai providers** command group has commands for managing AI providers.
```
pw ai providers [flags]
```
### Options
```
-h, --help help for providers
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai](/docs/cli/pw/ai) - Manage AI providers, models, and chats
* [pw ai providers create](/docs/cli/pw/ai/providers/create) - Create an AI provider
* [pw ai providers delete](/docs/cli/pw/ai/providers/delete) - Delete an AI provider
* [pw ai providers get](/docs/cli/pw/ai/providers/get) - Get details of an AI provider
* [pw ai providers ls](/docs/cli/pw/ai/providers/ls) - List AI providers
* [pw ai providers models](/docs/cli/pw/ai/providers/models) - List models available for a provider
# pw ai providers create
> Source: https://parallelworks.com/docs/cli/pw/ai/providers/create
## pw ai providers create
Create an AI provider
### Synopsis
The **pw ai providers create** command creates a new AI provider from an
enabled platform catalog entry. The platform defines the provider type,
endpoint, and transport policy.
For API-key providers (openai, anthropic, grok, groq, together, fireworks,
mistral, deepseek, or an approved custom integration), --api-key is required.
For **azure-managed** providers, --region, --group, and --network are required.
```
pw ai providers create [flags]
```
### Examples
```
# Create a personal Grok provider
pw ai providers create --name my-grok --provider grok --api-key xai-xxx
# Provision a managed Azure provider
pw ai providers create --name my-azure --provider azure-managed --region eastus --group my-group --network my-network
```
### Options
```
--api-key string API key (required for API-key providers)
--group string Billing group (required for azure-managed)
-h, --help help for create
--model string Initial model deployment (azure-managed)
--name string Provider name (required)
--network string Network (required for azure-managed)
--provider string Catalog entry ID (required, e.g. openai, anthropic, grok, azure-managed)
--region string Region (required for azure-managed)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai providers](/docs/cli/pw/ai/providers) - Manage AI providers
# pw ai providers delete
> Source: https://parallelworks.com/docs/cli/pw/ai/providers/delete
## pw ai providers delete
Delete an AI provider
### Synopsis
The **pw ai providers delete** command deletes an AI provider.
You can specify a provider by name (defaults to your user) or by full URI (pw://user/name).
```
pw ai providers delete [flags]
```
### Examples
```
# Delete your own provider
pw ai providers delete my-provider
# Delete another user's provider
pw ai providers delete pw://other-user/their-provider
```
### Options
```
-h, --help help for delete
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai providers](/docs/cli/pw/ai/providers) - Manage AI providers
# pw ai providers get
> Source: https://parallelworks.com/docs/cli/pw/ai/providers/get
## pw ai providers get
Get details of an AI provider
### Synopsis
The **pw ai providers get** command retrieves details of a specific AI provider.
You can specify a provider by name (defaults to your user) or by full URI (pw://user/name).
```
pw ai providers get [flags]
```
### Examples
```
# Get your own provider
pw ai providers get my-provider
# Get another user's provider
pw ai providers get pw://other-user/their-provider
# Get as JSON
pw ai providers get -o json my-provider
```
### Options
```
-h, --help help for get
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai providers](/docs/cli/pw/ai/providers) - Manage AI providers
# pw ai providers ls
> Source: https://parallelworks.com/docs/cli/pw/ai/providers/ls
## pw ai providers ls
List AI providers
### Synopsis
The **pw ai providers ls** command lists all AI providers configured for the current user.
```
pw ai providers ls [flags]
```
### Examples
```
# List all providers
pw ai providers ls
# List as JSON
pw ai providers ls -o json
```
### Options
```
-h, --help help for ls
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai providers](/docs/cli/pw/ai/providers) - Manage AI providers
# pw ai providers models
> Source: https://parallelworks.com/docs/cli/pw/ai/providers/models
## pw ai providers models
List models available for a provider
### Synopsis
The **pw ai providers models** command lists the models available for a specific AI provider.
You can specify a provider by name (defaults to your user) or by full URI (pw://user/name).
```
pw ai providers models [flags]
```
### Examples
```
# List models for your own provider
pw ai providers models my-provider
# List models for another user's provider
pw ai providers models pw://other-user/their-provider
```
### Options
```
-h, --help help for models
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw ai providers](/docs/cli/pw/ai/providers) - Manage AI providers
# pw api
> Source: https://parallelworks.com/docs/cli/pw/api
## pw api
Make an authenticated request to the ACTIVATE API
### Synopsis
Make an authenticated HTTP request to the ACTIVATE API and print the response.
**pw api** is an escape hatch for endpoints the CLI doesn't wrap, for poking at
new routes, or for scripting against the raw API. It uses your current context's
credentials and platform host (honoring **--context**, **--platform-host**, and
**PW_API_KEY**), so no manual auth is needed.
Endpoints resolve under the API base, so **workflows** and **/api/workflows** are
equivalent. The method defaults to GET, or POST when a body is supplied. Pass
parameters with **-F**/**-f**: for GET they become query-string parameters,
otherwise a JSON request body.
Note: with **-i/--include**, response headers are shown for successful (2xx)
responses; on an HTTP error the response body is still printed and the exit code
is non-zero.
```
pw api [flags]
```
### Examples
```
# GET a list endpoint (paths resolve under /api)
pw api workflows
# Filter the response with jq
pw api -q '.[].name' workflows
# Fetch all pages of a list endpoint
pw api --paginate users
# POST with a typed JSON body (method defaults to POST)
pw api -X POST -F name=demo -F enabled=true -F count=3 some/route
# Send a raw body from stdin
echo '{"name":"demo"}' | pw api -X POST --input - some/route
# Include response status and headers
pw api -i workflows
# Override or add a request header
pw api -H "X-Custom: value" workflows
```
### Options
```
-F, --field stringArray Add a typed parameter in key=value format (repeatable)
-H, --header stringArray Add a request header in 'Key: Value' format (repeatable)
-h, --help help for api
-i, --include Include the HTTP response status line and headers in the output
--input string File to read the request body from (use '-' for stdin)
-q, --jq string Filter the JSON response using a jq expression
-X, --method string HTTP method for the request (default "GET")
--paginate Make additional requests to fetch all pages of results
-f, --raw-field stringArray Add a string parameter in key=value format (repeatable)
--silent Do not print the response body
-v, --verbose Print the HTTP request and the response status and headers (to stderr)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
# pw auth
> Source: https://parallelworks.com/docs/cli/pw/auth
## pw auth
Authenticate the CLI
### Synopsis
The **pw auth** command grants authorization to the PW CLI using either an API key or a short-term token.
After you enter **pw auth**, the CLI will prompt you to paste your credential on a new line.
On ACTIVATE, the PW CLI is pre-authenticated for user workspaces and existing clusters.
You only have to authenticate if you're accessing a cloud cluster or running the PW CLI locally.
Use **--context-name** to specify a custom name for the context. This is useful if you want multiple contexts for the same user/server combination.
For more information about this process, please see [Authentication](/docs/cli#authentication).
```
pw auth [flags]
```
### Options
```
--context-name string Name for the context (defaults to user@server)
-h, --help help for auth
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw auth identify-platform](/docs/cli/pw/auth/identify-platform) - Print effective platform host
* [pw auth whoami](/docs/cli/pw/auth/whoami) - Print effective user
# pw auth identify-platform
> Source: https://parallelworks.com/docs/cli/pw/auth/identify-platform
## pw auth identify-platform
Print effective platform host
### Synopsis
Use **pw auth identify-platform** to verify which platform CLI commands will be executed against.
Prints the currently targeted platform host.
```
pw auth identify-platform [flags]
```
### Options
```
-h, --help help for identify-platform
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw auth](/docs/cli/pw/auth) - Authenticate the CLI
# pw auth whoami
> Source: https://parallelworks.com/docs/cli/pw/auth/whoami
## pw auth whoami
Print effective user
### Synopsis
Use **pw auth whoami** to verify your authentication.
Prints the currently authenticated identity. Typically, this will be the username of the account used to authenticate. However, it can also be other values, such as `cluster-session:demo/democluster/1`.
```
pw auth whoami [flags]
```
### Options
```
-h, --help help for whoami
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw auth](/docs/cli/pw/auth) - Authenticate the CLI
# pw billing
> Source: https://parallelworks.com/docs/cli/pw/billing
## pw billing
Manage billing units, SKUs, allocations, and usage
```
pw billing [flags]
```
### Options
```
-h, --help help for billing
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw billing allocations](/docs/cli/pw/billing/allocations) - Manage allocations and their usage
* [pw billing skus](/docs/cli/pw/billing/skus) - Manage SKUs and their rate multipliers within a unit
* [pw billing units](/docs/cli/pw/billing/units) - Manage billing units and their pricing rules
# pw billing allocations
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations
## pw billing allocations
Manage allocations and their usage
```
pw billing allocations [flags]
```
### Options
```
-h, --help help for allocations
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing](/docs/cli/pw/billing) - Manage billing units, SKUs, allocations, and usage
* [pw billing allocations create](/docs/cli/pw/billing/allocations/create) - Create an allocation under a unit
* [pw billing allocations get](/docs/cli/pw/billing/allocations/get) - Show a single allocation
* [pw billing allocations ls](/docs/cli/pw/billing/allocations/ls) - List allocations in the org
* [pw billing allocations permissions](/docs/cli/pw/billing/allocations/permissions) - Manage allocation access for groups and the organization
* [pw billing allocations report](/docs/cli/pw/billing/allocations/report) - Daily usage summary for an allocation (returns JSON)
* [pw billing allocations rm](/docs/cli/pw/billing/allocations/rm) - Delete an allocation
* [pw billing allocations update](/docs/cli/pw/billing/allocations/update) - Update an allocation's total budget
* [pw billing allocations usage](/docs/cli/pw/billing/allocations/usage) - Post and list usage events for an allocation
# pw billing allocations create
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/create
## pw billing allocations create
Create an allocation under a unit
```
pw billing allocations create [flags]
```
### Examples
```
# A $10k budget denominated in the core-hours unit
pw billing allocations create --total 10000 --unit core-hours research-team
# A child allocation under a parent
pw billing allocations create --total 2000 --unit core-hours --parent research-team gpu-subteam
```
### Options
```
-h, --help help for create
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
--parent string Optional parent allocation name
--total float Total budget for the allocation
--unit string Unit this allocation is denominated in
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations](/docs/cli/pw/billing/allocations) - Manage allocations and their usage
# pw billing allocations get
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/get
## pw billing allocations get
Show a single allocation
```
pw billing allocations get [flags]
```
### Examples
```
pw billing allocations get -o json research-team
```
### Options
```
-h, --help help for get
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations](/docs/cli/pw/billing/allocations) - Manage allocations and their usage
# pw billing allocations ls
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/ls
## pw billing allocations ls
List allocations in the org
```
pw billing allocations ls [flags]
```
### Examples
```
pw billing allocations ls
pw billing allocations ls -o json
```
### Options
```
-h, --help help for ls
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations](/docs/cli/pw/billing/allocations) - Manage allocations and their usage
# pw billing allocations permissions
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/permissions
## pw billing allocations permissions
Manage allocation access for groups and the organization
```
pw billing allocations permissions [flags]
```
### Options
```
-h, --help help for permissions
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations](/docs/cli/pw/billing/allocations) - Manage allocations and their usage
* [pw billing allocations permissions grant](/docs/cli/pw/billing/allocations/permissions/grant) - Grant allocation access to a group or the whole organization
* [pw billing allocations permissions ls](/docs/cli/pw/billing/allocations/permissions/ls) - Show who can access this allocation
* [pw billing allocations permissions revoke](/docs/cli/pw/billing/allocations/permissions/revoke) - Revoke allocation access from a group or the whole organization
# pw billing allocations permissions grant
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/permissions/grant
## pw billing allocations permissions grant
Grant allocation access to a group or the whole organization
```
pw billing allocations permissions grant [flags]
```
### Examples
```
# Grant a group the admin permission
pw ... permissions grant --group data-scientists --admin
# Grant the entire organization read access
pw ... permissions grant --org-wide --read
```
### Options
```
--admin Target the allocation:admin permission
--group string Apply to a specific group
-h, --help help for grant
--org string Target organization (defaults to current context)
--org-wide Apply to the entire organization
--read Target the allocation:read permission
--use Target the allocation:use permission
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations permissions](/docs/cli/pw/billing/allocations/permissions) - Manage allocation access for groups and the organization
# pw billing allocations permissions ls
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/permissions/ls
## pw billing allocations permissions ls
Show who can access this allocation
```
pw billing allocations permissions ls [flags]
```
### Examples
```
pw ... permissions ls
pw ... permissions ls -o json
```
### Options
```
-h, --help help for ls
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations permissions](/docs/cli/pw/billing/allocations/permissions) - Manage allocation access for groups and the organization
# pw billing allocations permissions revoke
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/permissions/revoke
## pw billing allocations permissions revoke
Revoke allocation access from a group or the whole organization
```
pw billing allocations permissions revoke [flags]
```
### Examples
```
# Revoke a single permission from a group
pw ... permissions revoke --group data-scientists --admin
# Revoke all of a group's access
pw ... permissions revoke --group data-scientists
```
### Options
```
--admin Target the allocation:admin permission
--group string Apply to a specific group
-h, --help help for revoke
--org string Target organization (defaults to current context)
--org-wide Apply to the entire organization
--read Target the allocation:read permission
--use Target the allocation:use permission
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations permissions](/docs/cli/pw/billing/allocations/permissions) - Manage allocation access for groups and the organization
# pw billing allocations report
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/report
## pw billing allocations report
Daily usage summary for an allocation (returns JSON)
```
pw billing allocations report [flags]
```
### Examples
```
# Daily usage in June, grouped by SKU subtype
pw billing allocations report --start 2026-06-01 --end 2026-06-30 --group-by subtype research-team
```
### Options
```
--end string End date (YYYY-MM-DD, defaults to today)
--group-by string Group by (type, subtype, user, sku)
-h, --help help for report
--org string Target organization (defaults to current context)
--start string Start date (YYYY-MM-DD)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations](/docs/cli/pw/billing/allocations) - Manage allocations and their usage
# pw billing allocations rm
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/rm
## pw billing allocations rm
Delete an allocation
```
pw billing allocations rm [flags]
```
### Examples
```
pw billing allocations rm research-team
```
### Options
```
-h, --help help for rm
--org string Target organization (defaults to current context)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations](/docs/cli/pw/billing/allocations) - Manage allocations and their usage
# pw billing allocations update
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/update
## pw billing allocations update
Update an allocation's total budget
```
pw billing allocations update [flags]
```
### Examples
```
pw billing allocations update --total 15000 research-team
```
### Options
```
-h, --help help for update
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
--total float New total budget
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations](/docs/cli/pw/billing/allocations) - Manage allocations and their usage
# pw billing allocations usage
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/usage
## pw billing allocations usage
Post and list usage events for an allocation
```
pw billing allocations usage [flags]
```
### Options
```
-h, --help help for usage
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations](/docs/cli/pw/billing/allocations) - Manage allocations and their usage
* [pw billing allocations usage ls](/docs/cli/pw/billing/allocations/usage/ls) - List rated usage for an allocation
* [pw billing allocations usage post](/docs/cli/pw/billing/allocations/usage/post) - Record a usage event against an allocation
# pw billing allocations usage ls
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/usage/ls
## pw billing allocations usage ls
List rated usage for an allocation
```
pw billing allocations usage ls [flags]
```
### Examples
```
pw billing allocations usage ls research-team
pw billing allocations usage ls -o json research-team
```
### Options
```
-h, --help help for ls
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
--page-size int Maximum rows to return (default 50)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations usage](/docs/cli/pw/billing/allocations/usage) - Post and list usage events for an allocation
# pw billing allocations usage post
> Source: https://parallelworks.com/docs/cli/pw/billing/allocations/usage/post
## pw billing allocations usage post
Record a usage event against an allocation
```
pw billing allocations usage post [flags]
```
### Examples
```
# 64 core-hours of CPU usage in a time window
pw billing allocations usage post --sku SLURM_CPU_HOUR --quantity 64 \
--start 2026-06-23T10:00:00Z --end 2026-06-23T14:00:00Z \
--metadata jobId=12345 --metadata cluster=hpc1 research-team
```
### Options
```
--end string End time (RFC3339)
-h, --help help for post
--metadata stringArray Repeatable key=value metadata
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
--quantity float Quantity of usage
--sku string SKU code to attribute usage to
--start string Start time (RFC3339, e.g. 2026-06-23T10:00:00Z)
--user string Attribute usage to this user (org admins only)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing allocations usage](/docs/cli/pw/billing/allocations/usage) - Post and list usage events for an allocation
# pw billing skus
> Source: https://parallelworks.com/docs/cli/pw/billing/skus
## pw billing skus
Manage SKUs and their rate multipliers within a unit
```
pw billing skus [flags]
```
### Options
```
-h, --help help for skus
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing](/docs/cli/pw/billing) - Manage billing units, SKUs, allocations, and usage
* [pw billing skus create](/docs/cli/pw/billing/skus/create) - Create a SKU in a unit
* [pw billing skus get](/docs/cli/pw/billing/skus/get) - Show a single SKU (including archived)
* [pw billing skus ls](/docs/cli/pw/billing/skus/ls) - List SKUs in a unit
* [pw billing skus restore](/docs/cli/pw/billing/skus/restore) - Restore an archived SKU
* [pw billing skus rm](/docs/cli/pw/billing/skus/rm) - Archive a SKU (soft delete)
* [pw billing skus rules](/docs/cli/pw/billing/skus/rules) - Manage a SKU's rate history
* [pw billing skus update](/docs/cli/pw/billing/skus/update) - Update mutable fields of a SKU
# pw billing skus create
> Source: https://parallelworks.com/docs/cli/pw/billing/skus/create
## pw billing skus create
Create a SKU in a unit
```
pw billing skus create [flags]
```
### Examples
```
# A standard CPU core-hour SKU (rate 1)
pw billing skus create --code SLURM_CPU_HOUR --name "CPU Hour" --type Compute --subtype NodeHour core-hours
# A GPU SKU that bills 3x per core-hour
pw billing skus create --code SLURM_GPU_HOUR --name "GPU Hour" --type Compute --subtype NodeHour --rate 3 core-hours
```
### Options
```
--code string SKU code (e.g. SLURM_CPU_HOUR)
--description string Optional description
-h, --help help for create
--name string Display name
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
--rate float Initial SKU rate (units consumed per unit of usage quantity) (default 1)
--subtype string SKU subtype (e.g. NodeHour)
--type string SKU type (e.g. Compute)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing skus](/docs/cli/pw/billing/skus) - Manage SKUs and their rate multipliers within a unit
# pw billing skus get
> Source: https://parallelworks.com/docs/cli/pw/billing/skus/get
## pw billing skus get
Show a single SKU (including archived)
```
pw billing skus get [flags]
```
### Examples
```
pw billing skus get -o json core-hours
```
### Options
```
-h, --help help for get
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing skus](/docs/cli/pw/billing/skus) - Manage SKUs and their rate multipliers within a unit
# pw billing skus ls
> Source: https://parallelworks.com/docs/cli/pw/billing/skus/ls
## pw billing skus ls
List SKUs in a unit
```
pw billing skus ls [flags]
```
### Examples
```
# List live SKUs in a unit
pw billing skus ls core-hours
# Include archived SKUs
pw billing skus ls --include-archived core-hours
```
### Options
```
-h, --help help for ls
--include-archived Include archived (soft-deleted) SKUs
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing skus](/docs/cli/pw/billing/skus) - Manage SKUs and their rate multipliers within a unit
# pw billing skus restore
> Source: https://parallelworks.com/docs/cli/pw/billing/skus/restore
## pw billing skus restore
Restore an archived SKU
```
pw billing skus restore [flags]
```
### Examples
```
pw billing skus restore core-hours
```
### Options
```
-h, --help help for restore
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing skus](/docs/cli/pw/billing/skus) - Manage SKUs and their rate multipliers within a unit
# pw billing skus rm
> Source: https://parallelworks.com/docs/cli/pw/billing/skus/rm
## pw billing skus rm
Archive a SKU (soft delete)
```
pw billing skus rm [flags]
```
### Examples
```
pw billing skus rm core-hours
```
### Options
```
-h, --help help for rm
--org string Target organization (defaults to current context)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing skus](/docs/cli/pw/billing/skus) - Manage SKUs and their rate multipliers within a unit
# pw billing skus rules
> Source: https://parallelworks.com/docs/cli/pw/billing/skus/rules
## pw billing skus rules
Manage a SKU's rate history
```
pw billing skus rules [flags]
```
### Options
```
-h, --help help for rules
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing skus](/docs/cli/pw/billing/skus) - Manage SKUs and their rate multipliers within a unit
* [pw billing skus rules add](/docs/cli/pw/billing/skus/rules/add) - Add a new rate multiplier for a SKU, effective now
* [pw billing skus rules ls](/docs/cli/pw/billing/skus/rules/ls) - List a SKU's rate history
# pw billing skus rules add
> Source: https://parallelworks.com/docs/cli/pw/billing/skus/rules/add
## pw billing skus rules add
Add a new rate multiplier for a SKU, effective now
```
pw billing skus rules add [flags]
```
### Examples
```
# Make this SKU bill 3 units per quantity going forward
pw billing skus rules add --rate 3 core-hours
```
### Options
```
-h, --help help for add
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
--rate float Units consumed per unit of usage quantity
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing skus rules](/docs/cli/pw/billing/skus/rules) - Manage a SKU's rate history
# pw billing skus rules ls
> Source: https://parallelworks.com/docs/cli/pw/billing/skus/rules/ls
## pw billing skus rules ls
List a SKU's rate history
```
pw billing skus rules ls [flags]
```
### Examples
```
pw billing skus rules ls core-hours
```
### Options
```
-h, --help help for ls
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing skus rules](/docs/cli/pw/billing/skus/rules) - Manage a SKU's rate history
# pw billing skus update
> Source: https://parallelworks.com/docs/cli/pw/billing/skus/update
## pw billing skus update
Update mutable fields of a SKU
```
pw billing skus update [flags]
```
### Examples
```
# Fix a typo'd code
pw billing skus update --code SLURM_GPU_HOUR core-hours
# Rename and recategorize (type/subtype changes affect only future billing)
pw billing skus update --name "GPU Node Hour" --subtype GpuHour core-hours
```
### Options
```
--code string New SKU code
--description string New description
-h, --help help for update
--name string New display name
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
--subtype string New SKU subtype
--type string New SKU type
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing skus](/docs/cli/pw/billing/skus) - Manage SKUs and their rate multipliers within a unit
# pw billing units
> Source: https://parallelworks.com/docs/cli/pw/billing/units
## pw billing units
Manage billing units and their pricing rules
```
pw billing units [flags]
```
### Options
```
-h, --help help for units
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing](/docs/cli/pw/billing) - Manage billing units, SKUs, allocations, and usage
* [pw billing units create](/docs/cli/pw/billing/units/create) - Create a billing unit
* [pw billing units get](/docs/cli/pw/billing/units/get) - Show a unit and its pricing rule history
* [pw billing units ls](/docs/cli/pw/billing/units/ls) - List billing units
* [pw billing units rm](/docs/cli/pw/billing/units/rm) - Delete a billing unit and all its SKUs, rules, and history
* [pw billing units rules](/docs/cli/pw/billing/units/rules) - Manage unit pricing rules
# pw billing units create
> Source: https://parallelworks.com/docs/cli/pw/billing/units/create
## pw billing units create
Create a billing unit
```
pw billing units create [flags]
```
### Examples
```
# A dollar-denominated unit at $0.01 per unit
pw billing units create --cost-per-unit 0.01 core-hours
# A non-dollar consumption unit (no USD rate; usage is measured in raw
# SKU-weighted quantities, e.g. "premium requests")
pw billing units create --rated-in-usd=false premium-requests
```
### Options
```
--cost-per-unit float USD per unit (only used when --rated-in-usd) (default 1)
-h, --help help for create
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
--rated-in-usd Rate usage into USD via the unit's price; set false for a consumption unit measured in raw SKU-weighted quantities (default true)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing units](/docs/cli/pw/billing/units) - Manage billing units and their pricing rules
# pw billing units get
> Source: https://parallelworks.com/docs/cli/pw/billing/units/get
## pw billing units get
Show a unit and its pricing rule history
```
pw billing units get [flags]
```
### Examples
```
# Show a unit
pw billing units get core-hours
# Output as JSON
pw billing units get -o json core-hours
```
### Options
```
-h, --help help for get
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing units](/docs/cli/pw/billing/units) - Manage billing units and their pricing rules
# pw billing units ls
> Source: https://parallelworks.com/docs/cli/pw/billing/units/ls
## pw billing units ls
List billing units
```
pw billing units ls [flags]
```
### Examples
```
# List units in the current org
pw billing units ls
# Output as JSON
pw billing units ls -o json
```
### Options
```
-h, --help help for ls
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing units](/docs/cli/pw/billing/units) - Manage billing units and their pricing rules
# pw billing units rm
> Source: https://parallelworks.com/docs/cli/pw/billing/units/rm
## pw billing units rm
Delete a billing unit and all its SKUs, rules, and history
```
pw billing units rm [flags]
```
### Examples
```
# Delete a unit
pw billing units rm core-hours
```
### Options
```
-h, --help help for rm
--org string Target organization (defaults to current context)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing units](/docs/cli/pw/billing/units) - Manage billing units and their pricing rules
# pw billing units rules
> Source: https://parallelworks.com/docs/cli/pw/billing/units/rules
## pw billing units rules
Manage unit pricing rules
```
pw billing units rules [flags]
```
### Options
```
-h, --help help for rules
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing units](/docs/cli/pw/billing/units) - Manage billing units and their pricing rules
* [pw billing units rules add](/docs/cli/pw/billing/units/rules/add) - Add a new USD rate for a unit, effective now
# pw billing units rules add
> Source: https://parallelworks.com/docs/cli/pw/billing/units/rules/add
## pw billing units rules add
Add a new USD rate for a unit, effective now
```
pw billing units rules add [flags]
```
### Examples
```
# Set the core-hours rate to $0.02/unit going forward
pw billing units rules add --rate 0.02 core-hours
```
### Options
```
-h, --help help for add
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
--rate float USD rate per unit
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw billing units rules](/docs/cli/pw/billing/units/rules) - Manage unit pricing rules
# pw buckets
> Source: https://parallelworks.com/docs/cli/pw/buckets
## pw buckets
Manage cloud buckets
### Synopsis
The **buckets** command group lets you list bucket contents and copy, print, or delete objects in your cloud buckets.
```
pw buckets [flags]
```
### Options
```
-h, --help help for buckets
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw buckets cat](/docs/cli/pw/buckets/cat) - Print a bucket object
* [pw buckets cp](/docs/cli/pw/buckets/cp) - Copy files between local and buckets
* [pw buckets get-token](/docs/cli/pw/buckets/get-token) - Print temporary access credentials for a cloud bucket
* [pw buckets ls](/docs/cli/pw/buckets/ls) - List buckets or files
* [pw buckets rm](/docs/cli/pw/buckets/rm) - Remove files from buckets
# pw buckets cat
> Source: https://parallelworks.com/docs/cli/pw/buckets/cat
## pw buckets cat
Print a bucket object
### Synopsis
The **pw buckets cat** command prints a bucket object's contents to standard output.
Both PW URIs and CSP URIs are accepted. For more information about URIs, please see [this section](/docs/cli#about-uris).
```
pw buckets cat [bucket URI]/[file] [flags]
```
### Examples
```
# Print a file from a bucket
pw buckets cat pw://demo/demos3bucket/sample.txt
# Pipe a file from an AWS bucket to another command
pw buckets cat s3://demos3bucket/sample.json | jq .
```
### Options
```
-h, --help help for cat
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw buckets](/docs/cli/pw/buckets) - Manage cloud buckets
# pw buckets cp
> Source: https://parallelworks.com/docs/cli/pw/buckets/cp
## pw buckets cp
Copy files between local and buckets
### Synopsis
The **pw buckets cp** command must be followed by a source and a destination. The source and destination can be either a local file or a bucket URI.
Both PW URIs and CSP URIs are accepted. For more information about URIs, please see [this section](/docs/cli#about-uris).
When copying to/from a bucket with a PW URI, you must specify at least the bucket name. However, paths can be longer, such as `pw://[namespace]/[bucket-name]/[folder]/[folder2]/[folder3]/[file-name]`.
Recursive copies follow the same trailing slash rule as **cp** and **rsync**: a source without a trailing slash copies the directory itself, and a source with a trailing slash copies its contents. This holds in both directions.
```
pw buckets cp [source] [destination] [flags]
```
### Examples
```
# Upload a local file named sample.txt to a bucket named demos3bucket in the demo namespace
pw buckets cp sample.txt pw://demo/demos3bucket
# Download a file named sample.txt to a local file
pw buckets cp pw://demo/demos3bucket/sample.txt sample2.txt
# Download a file from Azure Blob Storage to a local folder, using the Azure URI
pw buckets cp https://azuredemo.blob.core.windows.net/azuredemo/sample.txt sample2.txt
# Recursive download of a folder, keeping the folder
# Result: ./downloads/sample-dir/a.txt, ./downloads/sample-dir/sub/b.txt, ...
pw buckets cp -r pw://demo/demos3bucket/sample-dir ./downloads
# Recursive download of a folder's contents, with a trailing slash
# Result: ./downloads/a.txt, ./downloads/sub/b.txt, ...
pw buckets cp -r pw://demo/demos3bucket/sample-dir/ ./downloads
# Recursive download of the entire bucket root into a local folder
# Result: ./downloads/
pw buckets cp -r pw://demo/demos3bucket ./downloads/
# Recursive upload of a folder, keeping the folder
# Result: pw://demo/demos3bucket/uploads/sample-dir/a.txt, ...
pw buckets cp -r ./sample-dir pw://demo/demos3bucket/uploads
# Recursive upload of a folder's contents, with a trailing slash
# Result: pw://demo/demos3bucket/uploads/a.txt, ...
pw buckets cp -r ./sample-dir/ pw://demo/demos3bucket/uploads
```
### Options
```
-h, --help help for cp
-r, --recursive Copy directories/prefixes recursively
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw buckets](/docs/cli/pw/buckets) - Manage cloud buckets
# pw buckets get-token
> Source: https://parallelworks.com/docs/cli/pw/buckets/get-token
## pw buckets get-token
Print temporary access credentials for a cloud bucket
### Synopsis
The **pw buckets get-token** command must be followed by a bucket URI.
Both PW URIs and CSP URIs are accepted. For more information about URIs, please see [this section](/docs/cli#about-uris).
The short-term tokens that this command prints are the same tokens seen [here](/docs/storage/transferring-data/obtaining-credentials).
```
pw buckets get-token [bucketURI] [flags]
```
### Options
```
-h, --help help for get-token
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw buckets](/docs/cli/pw/buckets) - Manage cloud buckets
# pw buckets ls
> Source: https://parallelworks.com/docs/cli/pw/buckets/ls
## pw buckets ls
List buckets or files
### Synopsis
The **pw buckets ls** command can be used with or without arguments.
When no arguments are provided, all buckets are listed.
If you provide a namespace, all buckets in that namespace will be listed.
If you provide a namespace and bucket name, the files in the bucket will be listed.
You can list individual directories in the bucket by providing the full path to the directory.
This command also supports using the same CSP URI format accepted by CSP CLIs. For more information about URIs, please see [this section](/docs/cli#about-uris).
Files are listed as a table of URI, size in bytes, and modified time. Use **-o list** for one URI per line, which is the form to pipe into other commands, or **-o json** for the same fields as structured output.
```
pw buckets ls [bucketURI] [flags]
```
### Examples
```
# List all buckets
pw buckets ls
# List all buckets in a namespace
pw buckets ls pw://[namespace]
# List files in a bucket
pw buckets ls pw://[namespace]/[bucket]
# List files in a bucket, using the AWS URI format
pw buckets ls s3://[aws-bucket-name]
# List files in a bucket, using the Google URI format
pw buckets ls gs://[google-bucket-name]
# List files in a bucket, using the Azure URI format
pw buckets ls https://[azure-bucket-name].blob.core.windows.net/[azure-bucket-name]
# List the first 10 files in a bucket
pw buckets ls --limit 10 s3://[aws-bucket-name]
# List files as one URI per line, for piping
pw buckets ls -o list s3://[aws-bucket-name]
# List files with their size and modified time as JSON
pw buckets ls -o json s3://[aws-bucket-name]
# List all buckets you have access to, displayed as a table
# Tables display URI, CSP, provisioning status, and CSP URI
pw buckets ls -o table
# List currently provisioned buckets with csp URIs
pw buckets ls --csp-uris
```
### Options
```
--csp-uris Show CSP URIs
-h, --help help for ls
--limit int Maximum number of results to list. Lists everything when unset
-o, --output OUTPUT_FORMAT Output format. One of: list, json, table (default table)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw buckets](/docs/cli/pw/buckets) - Manage cloud buckets
# pw buckets rm
> Source: https://parallelworks.com/docs/cli/pw/buckets/rm
## pw buckets rm
Remove files from buckets
### Synopsis
The **pw buckets rm** command must be followed by a bucket URI and file name.
Both PW URIs and CSP URIs are accepted. For more information about URIs, please see [this section](/docs/cli#about-uris).
Removing a folder needs **-r**, which deletes every object under the given prefix and asks first. **-f** skips the prompt, and reports success when the object is already gone.
```
pw buckets rm [bucket URI]/[file] [flags]
```
### Examples
```
# Delete a file named sample.txt from a bucket named demos3bucket
pw buckets rm pw://demo/demos3bucket/sample.txt
# Delete every object under a folder, after confirming
pw buckets rm -r pw://demo/demos3bucket/reports/
# Delete a folder without being asked
pw buckets rm -rf pw://demo/demos3bucket/reports/
# Succeed even if the object is already gone
pw buckets rm -f pw://demo/demos3bucket/sample.txt
```
### Options
```
-f, --force Do not prompt, and do not fail when the object does not exist
-h, --help help for rm
-r, --recursive Delete every object under the given prefix
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw buckets](/docs/cli/pw/buckets) - Manage cloud buckets
# pw cluster
> Source: https://parallelworks.com/docs/cli/pw/cluster
## pw cluster
Manage clusters
```
pw cluster [flags]
```
### Options
```
-h, --help help for cluster
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw cluster attach-storage](/docs/cli/pw/cluster/attach-storage) - Attach storage to a cluster
* [pw cluster ls](/docs/cli/pw/cluster/ls) - List clusters
# pw cluster attach-storage
> Source: https://parallelworks.com/docs/cli/pw/cluster/attach-storage
## pw cluster attach-storage
Attach storage to a cluster
### Synopsis
The **attach-storage** command attaches storage to a cluster at the specified mount point.
```
pw cluster attach-storage [flags]
```
### Examples
```
# Attach storage to a cluster
pw cluster attach-storage --cluster-uri pw://namespace/cluster-name --storage-uri pw://namespace/storage-name --mount-point=/mnt-point
```
### Options
```
--cluster-uri string URI of the cluster (required)
-h, --help help for attach-storage
--mount-point string Mount point for the storage (required)
--storage-uri string URI of the storage to attach (required)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw cluster](/docs/cli/pw/cluster) - Manage clusters
# pw cluster ls
> Source: https://parallelworks.com/docs/cli/pw/cluster/ls
## pw cluster ls
List clusters
```
pw cluster ls [URI] [flags]
```
### Examples
```
# List all clusters
pw cluster ls
# List clusters owned by the user "Jake.Thayne"
pw cluster ls pw://Jake.Thayne
# List a specific cluster by URI
pw cluster ls pw://Jake.Thayne/my-cluster
# List only clusters you own
pw cluster ls --owned
# List only provisioned clusters
pw cluster ls --status=active
# List all clusters, displayed as a table
# Tables display URI, Provision status, and Type
pw cluster ls -o table
```
### Options
```
-h, --help help for ls
-o, --output string Output format (json, table)
--owned Show only clusters owned by the authenticated user
--status string Filter clusters by status (e.g., active, off, failed). 'on' is accepted as an alias for 'active'.
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw cluster](/docs/cli/pw/cluster) - Manage clusters
# pw code
> Source: https://parallelworks.com/docs/cli/pw/code
## pw code
AI coding agent
### Synopsis
Start an AI coding agent that can read, write, and edit files in your
workspace. The agent uses tool-calling to execute tasks autonomously.
If no model is specified, you'll be prompted to choose one.
Run 'pw ai models ls' to list the model IDs available to you.
```
pw code [model] [flags]
```
### Examples
```
# Pick a model interactively
pw code
# Start with a specific model (see 'pw ai models ls')
pw code Jake.Thayne:openai/gpt-5.2
# One-shot prompt
pw code -p "find all TODO comments" Jake.Thayne:openai/gpt-5.2
# JSON output for automation
pw code -p "list Go files" -o json Jake.Thayne:openai/gpt-5.2
# Resume a local session
pw code -r latest Jake.Thayne:openai/gpt-5.2
# Read-only mode
pw code --permission-mode read-only Jake.Thayne:openai/gpt-5.2
# Use an org provider with a budget allocation
pw code --allocation PW-QA-TEST org:openai/gpt-5.2
```
### Options
```
--add-dir strings Directories outside the workspace the agent may read without prompting (repeatable)
--agent string Run a custom agent definition as the main session (a name from .agents/agents)
--agents string Ad-hoc agent definitions as JSON keyed by name, merged over the definition files
--allocation string Budget allocation name (required for org provider models)
--allowedTools strings Tools pre-approved without prompting, e.g. ReadFile, 'Bash(git status:*)', or 'ReadFile(/data/**)' to allow reads outside the workspace
--effort string Reasoning effort: default, none, minimal, low, medium, high, xhigh, or max (support varies by model)
-h, --help help for code
-m, --model string Model ID, e.g. Jake.Thayne:openai/gpt-5.2 or org:openai/gpt-5.2 (run 'pw ai models ls' to list)
--no-tools Disable tool calling (chat-only mode)
-o, --output string Output format: text, json (default "text")
--permission-mode string Permission mode: read-only, accept-edits, bypass-permissions, plan
-p, --prompt string One-shot prompt (non-interactive)
-r, --resume string[=" pick"] Resume a local session: pass a session ID or 'latest', or use --resume alone to pick from a list
-w, --workspace string Workspace root directory (default: current directory)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw code mcp](/docs/cli/pw/code/mcp) - Manage MCP servers for pw code
# pw code mcp
> Source: https://parallelworks.com/docs/cli/pw/code/mcp
## pw code mcp
Manage MCP servers for pw code
### Synopsis
Manage the MCP servers pw code connects to.
Servers are stored in config files at four scopes, from lowest to
highest load precedence: user (~/.config/pw/code.json),
project (/.mcp.json), agents (/.agents/settings.json),
and local (/.agents/settings.local.json). At load time the
highest-precedence file with any servers supplies the entire set.
```
pw code mcp [flags]
```
### Options
```
-h, --help help for mcp
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw code](/docs/cli/pw/code) - AI coding agent
* [pw code mcp add](/docs/cli/pw/code/mcp/add) - Add an MCP server
* [pw code mcp get](/docs/cli/pw/code/mcp/get) - Show one MCP server's configuration
* [pw code mcp list](/docs/cli/pw/code/mcp/list) - List configured MCP servers across config files
* [pw code mcp remove](/docs/cli/pw/code/mcp/remove) - Remove an MCP server
# pw code mcp add
> Source: https://parallelworks.com/docs/cli/pw/code/mcp/add
## pw code mcp add
Add an MCP server
### Synopsis
Add an MCP server to a pw code config file.
stdio servers take their command (and arguments) after "--"; http and
sse servers take the endpoint URL as the second positional argument.
Run with no arguments in a terminal to be prompted for each value.
```
pw code mcp add [flags] [url] [-- [args...]]
```
### Examples
```
# Add a stdio server to /.agents/settings.local.json (default scope)
pw code mcp add -e API_KEY=secret everything -- npx -y @modelcontextprotocol/server-everything
# Add an HTTP server to the shared /.mcp.json
pw code mcp add --transport http -H "Authorization: Bearer token" --scope project context7 https://mcp.context7.com/mcp
# Fill in every value interactively
pw code mcp add
```
### Options
```
-e, --env stringArray Environment variable for a stdio server, KEY=VALUE (repeatable)
--force Overwrite an existing server with the same name
-H, --header stringArray HTTP header for an http/sse server, 'Key: Value' (repeatable)
-h, --help help for add
--scope string Config file to write: user, project, agents, or local (default: local)
--timeout string Connection timeout: milliseconds (60000) or a duration (60s)
-t, --transport string Transport: stdio, http, or sse (default: inferred from command/url)
-w, --workspace string Workspace root directory (default: current directory)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw code mcp](/docs/cli/pw/code/mcp) - Manage MCP servers for pw code
# pw code mcp get
> Source: https://parallelworks.com/docs/cli/pw/code/mcp/get
## pw code mcp get
Show one MCP server's configuration
```
pw code mcp get [flags]
```
### Options
```
-h, --help help for get
-o, --output string Output format: text, json (default "json")
--scope string Only search one config file: user, project, agents, or local
-w, --workspace string Workspace root directory (default: current directory)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw code mcp](/docs/cli/pw/code/mcp) - Manage MCP servers for pw code
# pw code mcp list
> Source: https://parallelworks.com/docs/cli/pw/code/mcp/list
## pw code mcp list
List configured MCP servers across config files
```
pw code mcp list [flags]
```
### Options
```
-h, --help help for list
-o, --output string Output format: text, json (default "text")
--scope string Only show one config file: user, project, agents, or local
-w, --workspace string Workspace root directory (default: current directory)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw code mcp](/docs/cli/pw/code/mcp) - Manage MCP servers for pw code
# pw code mcp remove
> Source: https://parallelworks.com/docs/cli/pw/code/mcp/remove
## pw code mcp remove
Remove an MCP server
```
pw code mcp remove [flags]
```
### Options
```
-h, --help help for remove
--scope string Config file to remove from: user, project, agents, or local
-w, --workspace string Workspace root directory (default: current directory)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw code mcp](/docs/cli/pw/code/mcp) - Manage MCP servers for pw code
# pw context
> Source: https://parallelworks.com/docs/cli/pw/context
## pw context
Manage CLI contexts
### Synopsis
The **pw context** command group lets you manage multiple CLI identities and switch between them.
Contexts allow you to authenticate with multiple Parallel Works platforms or user accounts
and easily switch between them without re-authenticating.
Each context stores the authentication credentials (API key or token), the platform server,
and the associated organization.
```
pw context [flags]
```
### Options
```
-h, --help help for context
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw context current](/docs/cli/pw/context/current) - Show the current context
* [pw context delete](/docs/cli/pw/context/delete) - Delete a context
* [pw context list](/docs/cli/pw/context/list) - List all available contexts
* [pw context rename](/docs/cli/pw/context/rename) - Rename a context
* [pw context use](/docs/cli/pw/context/use) - Switch to a different context
# pw context current
> Source: https://parallelworks.com/docs/cli/pw/context/current
## pw context current
Show the current context
### Synopsis
The **pw context current** command displays the name of the current context.
```
pw context current [flags]
```
### Examples
```
# Show the current context
pw context current
# Using alias
pw ctx current
```
### Options
```
-h, --help help for current
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw context](/docs/cli/pw/context) - Manage CLI contexts
# pw context delete
> Source: https://parallelworks.com/docs/cli/pw/context/delete
## pw context delete
Delete a context
### Synopsis
The **pw context delete** command removes a context from the credentials file.
If the context being deleted is the current one, you must use the --force flag.
When deleting the current context with --force, another available context will be
selected as the new current context automatically.
```
pw context delete [flags]
```
### Examples
```
# Delete a context
pw context delete user@staging.parallel.works
# Force delete the current context
pw context delete --force user@activate.parallel.works
# Using alias
pw ctx delete old-context
```
### Options
```
-f, --force Force delete even if this is the current context
-h, --help help for delete
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw context](/docs/cli/pw/context) - Manage CLI contexts
# pw context list
> Source: https://parallelworks.com/docs/cli/pw/context/list
## pw context list
List all available contexts
### Synopsis
The **pw context list** command displays all available contexts.
The current context is marked with an asterisk (*).
```
pw context list [flags]
```
### Examples
```
# List all contexts (simple list)
pw context list
# List all contexts as a table
pw context list -o table
# List all contexts as JSON
pw context list -o json
# Using alias
pw ctx list
```
### Options
```
-h, --help help for list
-o, --output OUTPUT_FORMAT Output format. One of: list, json, table (default table)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw context](/docs/cli/pw/context) - Manage CLI contexts
# pw context rename
> Source: https://parallelworks.com/docs/cli/pw/context/rename
## pw context rename
Rename a context
### Synopsis
The **pw context rename** command renames an existing context.
If the renamed context is the current one, the current context reference is updated automatically.
```
pw context rename [flags]
```
### Examples
```
# Rename a context
pw context rename user@activate.parallel.works production
# Using alias
pw ctx rename old-context new-context
```
### Options
```
-h, --help help for rename
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw context](/docs/cli/pw/context) - Manage CLI contexts
# pw context use
> Source: https://parallelworks.com/docs/cli/pw/context/use
## pw context use
Switch to a different context
### Synopsis
The **pw context use** command switches the current context to the specified one.
After switching, all subsequent commands will use the credentials from the selected context.
```
pw context use [flags]
```
### Examples
```
# Switch to a different context
pw context use user@activate.parallel.works
# Using alias
pw ctx use user@staging.parallel.works
```
### Options
```
-h, --help help for use
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw context](/docs/cli/pw/context) - Manage CLI contexts
# pw endpoints
> Source: https://parallelworks.com/docs/cli/pw/endpoints
## pw endpoints
Create and serve self-registering endpoint sessions
### Synopsis
Endpoint sessions expose a locally-running web app through the platform by
dialing out and registering a reverse tunnel — no inbound network access to
your machine is required.
Run **endpoints http PORT** next to an app listening on that port, or
**endpoints http SOCKET_PATH** next to an app listening on a Unix socket. Use
**endpoints https** instead when the local app speaks TLS. The platform forwards
its session URL to your local server until you exit.
```
pw endpoints [flags]
```
### Options
```
-h, --help help for endpoints
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw endpoints delete](/docs/cli/pw/endpoints/delete) - Delete an endpoint session
* [pw endpoints http](/docs/cli/pw/endpoints/http) - Serve a local HTTP app as an endpoint
* [pw endpoints https](/docs/cli/pw/endpoints/https) - Serve a local HTTPS app as an endpoint
* [pw endpoints list](/docs/cli/pw/endpoints/list) - List your endpoint sessions
* [pw endpoints run](/docs/cli/pw/endpoints/run) - Run a command that serves HTTP and expose it as an endpoint
* [pw endpoints serve](/docs/cli/pw/endpoints/serve) - Serve a static site directory as an endpoint
# pw endpoints delete
> Source: https://parallelworks.com/docs/cli/pw/endpoints/delete
## pw endpoints delete
Delete an endpoint session
```
pw endpoints delete [flags]
```
### Options
```
-h, --help help for delete
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw endpoints](/docs/cli/pw/endpoints) - Create and serve self-registering endpoint sessions
# pw endpoints http
> Source: https://parallelworks.com/docs/cli/pw/endpoints/http
## pw endpoints http
Serve a local HTTP app as an endpoint
### Synopsis
Serve a local app through the platform: the CLI dials out and registers a
reverse tunnel, then forwards the session URL to your app until you exit.
Local dev servers (Next.js, Vite, etc.) see requests arriving from the public
endpoint host rather than localhost, so their Hot Module Reload socket and
dev-only routes are treated as cross-origin and may be blocked — the page loads
but never finishes updating and the browser console shows repeated HMR WebSocket
failures. Allow the endpoint host in your dev server's config to fix it (Next.js
**allowedDevOrigins**, Vite **server.allowedHosts**).
Add **--openai** to expose a local OpenAI-compatible server (a /v1 endpoint such
as vLLM or Ollama) as a model in the platform chat and AI providers. Use
**--auth-file** if that server requires an API key.
```
pw endpoints http (PORT | SOCKET_PATH) [flags]
```
### Examples
```
# Serve a local app on port 5173 as an endpoint
pw endpoints http 5173
# Serve a local app listening on a Unix socket
pw endpoints http /tmp/app.sock
# Give it a name and open it in the browser
pw endpoints http --name my_app --open 3000
# Serve it publicly so anyone with the link can reach it without logging in
pw endpoints http --public 3000
# Expose a local OpenAI-compatible server (e.g. Ollama) as a chat model
pw endpoints http --openai --name my_llm 11434
```
### Options
```
--auth-file string File containing an Authorization header value or token to forward to the local app
--auth-scheme string Authorization scheme used when --auth-file contains only a raw token (default "Bearer")
--description string Session description (defaults to "Endpoint on ")
-h, --help help for http
--keep Keep the endpoint session on exit instead of deleting it
--link Stop the local server process listening on the target port when this command exits
-n, --name string Name for the endpoint session (defaults to a server-generated name)
--no-subdomain Skip subdomain assignment and use the path-based session URL
--open Open the endpoint URL in the browser
--openai Expose this endpoint as an OpenAI-compatible model in the platform chat and AI providers. Point it at a local /v1 server (vLLM, Ollama, etc.); pass --auth-file if that server needs an API key.
-o, --output string Output format (interactive, text); interactive shows a live dashboard and downgrades to text when stdout is not a terminal (default "interactive")
--public Make the endpoint publicly accessible: anyone with the link can reach it without logging in. Requires your organization to allow public sessions.
--rewrite-host string[="localhost"] Rewrite the Host header sent to your local app to this value (defaults to "localhost" when the flag is given without one). Use for an app that rejects the public endpoint host, such as a DNS-rebinding guard or an allowed-hosts check.
--slug string Session base-path slug (default "/")
--strip-path Strip the session URL prefix before forwarding to your app (use only if your app serves at the root path and can't be configured with a base path; by default the full path is forwarded so set your app's base path to the endpoint URL)
-s, --subdomain string Serve at this subdomain: a label (my-app), which lands on the platform's default sessions domain, or the full host under any registered sessions domain (my-app.); a random subdomain is used by default when the platform supports them
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw endpoints](/docs/cli/pw/endpoints) - Create and serve self-registering endpoint sessions
# pw endpoints https
> Source: https://parallelworks.com/docs/cli/pw/endpoints/https
## pw endpoints https
Serve a local HTTPS app as an endpoint
### Synopsis
Serve a local app through the platform: the CLI dials out and registers a
reverse tunnel, then forwards the session URL to your app until you exit.
Local dev servers (Next.js, Vite, etc.) see requests arriving from the public
endpoint host rather than localhost, so their Hot Module Reload socket and
dev-only routes are treated as cross-origin and may be blocked — the page loads
but never finishes updating and the browser console shows repeated HMR WebSocket
failures. Allow the endpoint host in your dev server's config to fix it (Next.js
**allowedDevOrigins**, Vite **server.allowedHosts**).
Add **--openai** to expose a local OpenAI-compatible server (a /v1 endpoint such
as vLLM or Ollama) as a model in the platform chat and AI providers. Use
**--auth-file** if that server requires an API key.
```
pw endpoints https (PORT | SOCKET_PATH) [flags]
```
### Examples
```
# Serve a local app on port 5173 as an endpoint
pw endpoints https 5173
# Serve a local app listening on a Unix socket
pw endpoints https /tmp/app.sock
# Give it a name and open it in the browser
pw endpoints https --name my_app --open 3000
# Serve it publicly so anyone with the link can reach it without logging in
pw endpoints https --public 3000
# Expose a local OpenAI-compatible server (e.g. Ollama) as a chat model
pw endpoints https --openai --name my_llm 11434
```
### Options
```
--auth-file string File containing an Authorization header value or token to forward to the local app
--auth-scheme string Authorization scheme used when --auth-file contains only a raw token (default "Bearer")
--description string Session description (defaults to "Endpoint on ")
-h, --help help for https
--keep Keep the endpoint session on exit instead of deleting it
--link Stop the local server process listening on the target port when this command exits
-n, --name string Name for the endpoint session (defaults to a server-generated name)
--no-subdomain Skip subdomain assignment and use the path-based session URL
--open Open the endpoint URL in the browser
--openai Expose this endpoint as an OpenAI-compatible model in the platform chat and AI providers. Point it at a local /v1 server (vLLM, Ollama, etc.); pass --auth-file if that server needs an API key.
-o, --output string Output format (interactive, text); interactive shows a live dashboard and downgrades to text when stdout is not a terminal (default "interactive")
--public Make the endpoint publicly accessible: anyone with the link can reach it without logging in. Requires your organization to allow public sessions.
--rewrite-host string[="localhost"] Rewrite the Host header sent to your local app to this value (defaults to "localhost" when the flag is given without one). Use for an app that rejects the public endpoint host, such as a DNS-rebinding guard or an allowed-hosts check.
--slug string Session base-path slug (default "/")
--strip-path Strip the session URL prefix before forwarding to your app (use only if your app serves at the root path and can't be configured with a base path; by default the full path is forwarded so set your app's base path to the endpoint URL)
-s, --subdomain string Serve at this subdomain: a label (my-app), which lands on the platform's default sessions domain, or the full host under any registered sessions domain (my-app.); a random subdomain is used by default when the platform supports them
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw endpoints](/docs/cli/pw/endpoints) - Create and serve self-registering endpoint sessions
# pw endpoints list
> Source: https://parallelworks.com/docs/cli/pw/endpoints/list
## pw endpoints list
List your endpoint sessions
```
pw endpoints list [flags]
```
### Options
```
-h, --help help for list
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw endpoints](/docs/cli/pw/endpoints) - Create and serve self-registering endpoint sessions
# pw endpoints run
> Source: https://parallelworks.com/docs/cli/pw/endpoints/run
## pw endpoints run
Run a command that serves HTTP and expose it as an endpoint
### Synopsis
Spawn a command that serves HTTP on a local port and forward it through an
endpoint, tearing the whole process tree down when this command exits.
The CLI assigns a free local port; reference it in your command with the
{port} token, or read it from the PORT environment variable. Reference the
endpoint's public hostname with the {host} token (also exported as `PW_ENDPOINT_HOST`)
to give a dev server the public host it must allow-list. Reference the base path
the endpoint is served under with the {path} token (also exported as `PW_ENDPOINT_PATH`):
"/me/session///" for a path-based endpoint (--no-subdomain) or "/" for a subdomain
one. Set an app's base path to it so its links resolve behind the prefix, such as Jupyter's
--ServerApp.base_url. The full public URL is exported as `PW_ENDPOINT_URL`.
```
pw endpoints run -- COMMAND [ARGS...] [flags]
```
### Examples
```
# Run a Jupyter server and expose it (port substituted into the command)
pw endpoints run -- jupyter lab --port {port} --no-browser --ServerApp.allow_remote_access=True
# Same, on a path-based endpoint: {path} sets Jupyter's base URL to the session prefix
pw endpoints run --no-subdomain --name jupyter -- jupyter lab --port {port} --no-browser --ServerApp.allow_remote_access=True --ServerApp.base_url={path}
# Run a node server that reads $PORT
pw endpoints run --name api -- node server.js
# Serve an Ollama model (--rewrite-host satisfies its host guard; sh -c sets its OLLAMA_HOST bind var)
pw endpoints run --rewrite-host -- sh -c 'OLLAMA_HOST=127.0.0.1:{port} ollama serve'
# Serve a model with llama.cpp (llama-server takes --port directly)
pw endpoints run -- llama-server -hf ggml-org/gpt-oss-20b-GGUF --port {port}
# Give an app its public host so it accepts requests through the endpoint
pw endpoints run -- my-dev-server --allowed-host {host}
# Pin the local port
pw endpoints run --port 5173 -- npm run dev
```
### Options
```
--description string Session description (defaults to "Endpoint on ")
-h, --help help for run
--keep Keep the endpoint session on exit instead of deleting it
-n, --name string Name for the endpoint session (defaults to a server-generated name)
--no-subdomain Skip subdomain assignment and use the path-based session URL
--open Open the endpoint URL in the browser
--openai Expose this endpoint as an OpenAI-compatible model in the platform chat and AI providers. Point it at a local /v1 server (vLLM, Ollama, etc.); pass --auth-file if that server needs an API key.
-o, --output string Output format (interactive, text); interactive shows a live dashboard and downgrades to text when stdout is not a terminal (default "interactive")
-p, --port int Local port to assign the command (default: a free port chosen automatically)
--public Make the endpoint publicly accessible: anyone with the link can reach it without logging in. Requires your organization to allow public sessions.
--rewrite-host string[="localhost"] Rewrite the Host header sent to your local app to this value (defaults to "localhost" when the flag is given without one). Use for an app that rejects the public endpoint host, such as a DNS-rebinding guard or an allowed-hosts check.
--slug string Session base-path slug (default "/")
--strip-path Strip the session URL prefix before forwarding to your app (use only if your app serves at the root path and can't be configured with a base path; by default the full path is forwarded so set your app's base path to the endpoint URL)
-s, --subdomain string Serve at this subdomain: a label (my-app), which lands on the platform's default sessions domain, or the full host under any registered sessions domain (my-app.); a random subdomain is used by default when the platform supports them
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw endpoints](/docs/cli/pw/endpoints) - Create and serve self-registering endpoint sessions
# pw endpoints serve
> Source: https://parallelworks.com/docs/cli/pw/endpoints/serve
## pw endpoints serve
Serve a static site directory as an endpoint
### Synopsis
Serve a built single-page-app directory (e.g. a Vite "dist") through an
endpoint. The CLI runs a static file server with SPA history fallback on a
local port and forwards it — no separate web server needed.
Use a subdomain (the default) so the app is served at the domain root and a
standard base:'/' build works unchanged.
```
pw endpoints serve DIR [flags]
```
### Examples
```
# Serve a built SPA
pw endpoints serve ./dist
# Named and opened in the browser
pw endpoints serve --name my_app --open ./dist
```
### Options
```
--description string Session description (defaults to "Endpoint on ")
-h, --help help for serve
--keep Keep the endpoint session on exit instead of deleting it
-n, --name string Name for the endpoint session (defaults to a server-generated name)
--no-subdomain Skip subdomain assignment and use the path-based session URL
--open Open the endpoint URL in the browser
-o, --output string Output format (interactive, text); interactive shows a live dashboard and downgrades to text when stdout is not a terminal (default "interactive")
--public Make the endpoint publicly accessible: anyone with the link can reach it without logging in. Requires your organization to allow public sessions.
--rewrite-host string[="localhost"] Rewrite the Host header sent to your local app to this value (defaults to "localhost" when the flag is given without one). Use for an app that rejects the public endpoint host, such as a DNS-rebinding guard or an allowed-hosts check.
--slug string Session base-path slug (default "/")
--strip-path Strip the session URL prefix before forwarding to your app (use only if your app serves at the root path and can't be configured with a base path; by default the full path is forwarded so set your app's base path to the endpoint URL)
-s, --subdomain string Serve at this subdomain: a label (my-app), which lands on the platform's default sessions domain, or the full host under any registered sessions domain (my-app.); a random subdomain is used by default when the platform supports them
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw endpoints](/docs/cli/pw/endpoints) - Create and serve self-registering endpoint sessions
# pw environments
> Source: https://parallelworks.com/docs/cli/pw/environments
## pw environments
Manage compute environments
### Synopsis
The **pw environments** command group has commands for managing the compute
environments on a cluster. An environment describes a scheduler partition
that sessions can be scheduled onto, along with the parameters users may set
when scheduling.
Environments the cluster detects for itself have a source of
**auto-detected** and cannot be deleted. Environments you create have a
source of **custom**.
Every command takes the cluster with **--cluster**, given as
**pw://user/cluster** for a cluster owned by another user or as **cluster** for
one of your own. Environment names are unique only within their cluster, so
they are named by name or ID alongside **--cluster** rather than by URI.
```
pw environments [flags]
```
### Options
```
-h, --help help for environments
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw environments create](/docs/cli/pw/environments/create) - Create a custom environment on a cluster
* [pw environments delete](/docs/cli/pw/environments/delete) - Delete a custom environment
* [pw environments get](/docs/cli/pw/environments/get) - Get details of an environment
* [pw environments ls](/docs/cli/pw/environments/ls) - List compute environments
* [pw environments update](/docs/cli/pw/environments/update) - Update an environment
# pw environments create
> Source: https://parallelworks.com/docs/cli/pw/environments/create
## pw environments create
Create a custom environment on a cluster
### Synopsis
The **pw environments create** command creates a custom compute environment on
a cluster, mapping a scheduler partition to an environment that sessions can
be scheduled onto.
The cluster can be given as **pw://user/cluster** for a cluster owned by
another user, or as **cluster** for one of your own.
Wall times are given in the scheduler's own format, for example **24:00:00**.
```
pw environments create [flags]
```
### Examples
```
# Create a Slurm environment for the gpu partition
pw environments create --cluster my-hpc --name gpu-large --partition gpu --scheduler slurm
# Create an environment with a display name and wall time limits
pw environments create --cluster my-hpc --name gpu-large --partition gpu --scheduler slurm \
--display-name "GPU (large)" --max-time 24:00:00 --default-time 01:00:00
# Create a PBS environment on another user's cluster
pw environments create --cluster pw://Jake.Thayne/my-hpc --name debug --partition debug --scheduler pbs
```
### Options
```
--cluster string Cluster to create the environment on (required)
--default-time string Default wall time, for example 01:00:00
--description string Description of the environment
--display-name string Human-readable name shown in the UI
-h, --help help for create
--max-time string Maximum wall time, for example 24:00:00
--name string Environment name, unique within the cluster (required)
--partition string Scheduler partition to map to (required)
--scheduler string Scheduler type: slurm or pbs (required)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw environments](/docs/cli/pw/environments) - Manage compute environments
# pw environments delete
> Source: https://parallelworks.com/docs/cli/pw/environments/delete
## pw environments delete
Delete a custom environment
### Synopsis
The **pw environments delete** command deletes a custom environment.
Environments the cluster detected for itself have a source of
**auto-detected** and cannot be deleted. To stop sessions being scheduled onto
one, run **pw environments update --status inactive** instead.
```
pw environments delete [flags]
```
### Examples
```
# Delete a custom environment
pw environments delete --cluster my-hpc gpu-large
# Delete an environment on another user's cluster
pw environments delete --cluster pw://Jake.Thayne/my-hpc gpu-large
```
### Options
```
--cluster string Cluster the environment belongs to (required)
-h, --help help for delete
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw environments](/docs/cli/pw/environments) - Manage compute environments
# pw environments get
> Source: https://parallelworks.com/docs/cli/pw/environments/get
## pw environments get
Get details of an environment
### Synopsis
The **pw environments get** command shows an environment's configuration and
the parameters that can be set when scheduling a session onto it.
The environment can be given by name or by ID. The cluster can be given as
**pw://user/cluster** for a cluster owned by another user, or as **cluster**
for one of your own.
```
pw environments get [flags]
```
### Examples
```
# Get an environment on one of your clusters
pw environments get --cluster my-hpc gpu-large
# Get an environment on another user's cluster
pw environments get --cluster pw://Jake.Thayne/my-hpc gpu-large
# Get as JSON
pw environments get --cluster my-hpc -o json gpu-large
```
### Options
```
--cluster string Cluster the environment belongs to (required)
-h, --help help for get
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw environments](/docs/cli/pw/environments) - Manage compute environments
# pw environments ls
> Source: https://parallelworks.com/docs/cli/pw/environments/ls
## pw environments ls
List compute environments
### Synopsis
The **pw environments ls** command lists compute environments.
Without **--cluster** it lists every environment across the clusters you can
schedule on, with a cluster column.
Pass **--cluster** to list one cluster, given as **pw://user/cluster** for a
cluster owned by another user or as **cluster** for one of your own.
```
pw environments ls [flags]
```
### Examples
```
# List the environments on every cluster you can schedule on
pw environments ls
# List the environments on one of your clusters
pw environments ls --cluster my-hpc
# List the environments on another user's cluster
pw environments ls --cluster pw://Jake.Thayne/my-hpc
# List only active environments
pw environments ls --status active
# List as JSON
pw environments ls -o json
```
### Options
```
--cluster string Cluster to list environments on (default: every cluster you can schedule on)
-h, --help help for ls
-o, --output string Output format (table, json, list) (default "table")
--status string Filter environments by status (active, inactive)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw environments](/docs/cli/pw/environments) - Manage compute environments
# pw environments update
> Source: https://parallelworks.com/docs/cli/pw/environments/update
## pw environments update
Update an environment
### Synopsis
The **pw environments update** command updates an environment's configuration.
Only the settings you pass are changed.
Setting **--status inactive** keeps the environment but stops sessions from
being scheduled onto it.
Use **--default** to set the value a scheduling parameter takes when a session
does not specify one. Run **pw environments get** to see which parameters an
environment accepts.
```
pw environments update [flags]
```
### Examples
```
# Rename an environment for display
pw environments update --cluster my-hpc --display-name "GPU (large)" gpu-large
# Stop new sessions being scheduled onto an environment
pw environments update --cluster my-hpc --status inactive gpu-large
# Raise the wall time limit
pw environments update --cluster my-hpc --max-time 48:00:00 gpu-large
# Default sessions on this environment to 2 nodes
pw environments update --cluster my-hpc --default numNodes=2 gpu-large
```
### Options
```
--cluster string Cluster the environment belongs to (required)
--default stringArray Default value for a scheduling parameter as key=value (repeatable)
--default-time string Default wall time, for example 01:00:00
--description string Description of the environment
--display-name string Human-readable name shown in the UI
-h, --help help for update
--max-time string Maximum wall time, for example 24:00:00
--status string Environment status: active or inactive
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw environments](/docs/cli/pw/environments) - Manage compute environments
# pw forward
> Source: https://parallelworks.com/docs/cli/pw/forward
## pw forward
Forward remote ports to your local machine via SSH tunnels
### Synopsis
The **pw forward** command creates SSH tunnels that make remote ports accessible on your
local machine. This uses the same mechanism as the -L option in OpenSSH.
Unlike **pw ssh -L**, this command automatically reconnects if the SSH connection is
interrupted. Local listeners stay open across reconnects, so client programs only see a
brief interruption rather than a closed port. This makes it ideal for long-lived tunnels.
A connection whose server stops answering keepalives is detected as dead, torn down, and
re-established automatically.
Resource names can be specified in the following formats:
- **pw://username/name** - full format with explicit username
- **pw://name** - managed cluster by name in your organization
- **name** - short format where username defaults to your username
```
pw forward -L [bind_address:]port:host:hostport [-L ...] [flags]
```
### Examples
```
# Make remote port 8080 accessible at localhost:8080
pw forward -L 8080:localhost:8080 my-cluster
# Forward multiple remote ports
pw forward -L 5900:localhost:5901 -L 3000:localhost:3000 my-cluster
# Bind to all interfaces (accessible from other machines on your network)
pw forward -L 0.0.0.0:8080:localhost:8080 my-cluster
# Forward a port from your user workspace
pw forward -L 8080:localhost:8080 workspace
```
### Options
```
-h, --help help for forward
--keepalive int Interval in seconds between keepalive messages; an unresponsive connection is torn down and reconnected (0 to disable) (default 30)
-L, --local stringArray Forward local [bind_address:]port to remote host:hostport (required, repeatable)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
# pw groups
> Source: https://parallelworks.com/docs/cli/pw/groups
## pw groups
Manage groups and their members
```
pw groups [flags]
```
### Options
```
-h, --help help for groups
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw groups create](/docs/cli/pw/groups/create) - Create a group
* [pw groups get](/docs/cli/pw/groups/get) - Show a group and its members
* [pw groups ls](/docs/cli/pw/groups/ls) - List groups in the organization
* [pw groups members](/docs/cli/pw/groups/members) - Manage group members
* [pw groups rm](/docs/cli/pw/groups/rm) - Delete a group
* [pw groups roles](/docs/cli/pw/groups/roles) - Manage a group's roles
* [pw groups update](/docs/cli/pw/groups/update) - Update a group's description
# pw groups create
> Source: https://parallelworks.com/docs/cli/pw/groups/create
## pw groups create
Create a group
```
pw groups create [flags]
```
### Examples
```
pw groups create --description "Research staff" research-team
# Create a group with org roles assigned
pw groups create --role org:admin --role org:users admins
```
### Options
```
--description string Group description
-h, --help help for create
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
--role stringArray Role to assign (repeatable, e.g. org:admin)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw groups](/docs/cli/pw/groups) - Manage groups and their members
# pw groups get
> Source: https://parallelworks.com/docs/cli/pw/groups/get
## pw groups get
Show a group and its members
```
pw groups get [flags]
```
### Examples
```
pw groups get research-team
pw groups get -o json research-team
```
### Options
```
-h, --help help for get
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw groups](/docs/cli/pw/groups) - Manage groups and their members
# pw groups ls
> Source: https://parallelworks.com/docs/cli/pw/groups/ls
## pw groups ls
List groups in the organization
```
pw groups ls [flags]
```
### Examples
```
pw groups ls
pw groups ls -o json
```
### Options
```
-h, --help help for ls
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw groups](/docs/cli/pw/groups) - Manage groups and their members
# pw groups members
> Source: https://parallelworks.com/docs/cli/pw/groups/members
## pw groups members
Manage group members
```
pw groups members [flags]
```
### Options
```
-h, --help help for members
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw groups](/docs/cli/pw/groups) - Manage groups and their members
* [pw groups members add](/docs/cli/pw/groups/members/add) - Add a member to a group
* [pw groups members ls](/docs/cli/pw/groups/members/ls) - List members of a group
* [pw groups members rm](/docs/cli/pw/groups/members/rm) - Remove a member from a group
# pw groups members add
> Source: https://parallelworks.com/docs/cli/pw/groups/members/add
## pw groups members add
Add a member to a group
```
pw groups members add [flags]
```
### Examples
```
pw groups members add research-team jake.thayne
```
### Options
```
-h, --help help for add
--org string Target organization (defaults to current context)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw groups members](/docs/cli/pw/groups/members) - Manage group members
# pw groups members ls
> Source: https://parallelworks.com/docs/cli/pw/groups/members/ls
## pw groups members ls
List members of a group
```
pw groups members ls [flags]
```
### Examples
```
pw groups members ls research-team
pw groups members ls -o json research-team
```
### Options
```
-h, --help help for ls
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw groups members](/docs/cli/pw/groups/members) - Manage group members
# pw groups members rm
> Source: https://parallelworks.com/docs/cli/pw/groups/members/rm
## pw groups members rm
Remove a member from a group
```
pw groups members rm [flags]
```
### Examples
```
pw groups members rm research-team jake.thayne
```
### Options
```
-h, --help help for rm
--org string Target organization (defaults to current context)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw groups members](/docs/cli/pw/groups/members) - Manage group members
# pw groups rm
> Source: https://parallelworks.com/docs/cli/pw/groups/rm
## pw groups rm
Delete a group
```
pw groups rm [flags]
```
### Examples
```
pw groups rm research-team
pw groups rm -f research-team
```
### Options
```
-f, --force Skip confirmation prompt
-h, --help help for rm
--org string Target organization (defaults to current context)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw groups](/docs/cli/pw/groups) - Manage groups and their members
# pw groups roles
> Source: https://parallelworks.com/docs/cli/pw/groups/roles
## pw groups roles
Manage a group's roles
```
pw groups roles [flags]
```
### Options
```
-h, --help help for roles
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw groups](/docs/cli/pw/groups) - Manage groups and their members
* [pw groups roles set](/docs/cli/pw/groups/roles/set) - Replace a group's roles
# pw groups roles set
> Source: https://parallelworks.com/docs/cli/pw/groups/roles/set
## pw groups roles set
Replace a group's roles
```
pw groups roles set [flags]
```
### Examples
```
pw groups roles set --role org:admin --role org:users admins
```
### Options
```
-h, --help help for set
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
--role stringArray Role to assign (repeatable, e.g. org:admin)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw groups roles](/docs/cli/pw/groups/roles) - Manage a group's roles
# pw groups update
> Source: https://parallelworks.com/docs/cli/pw/groups/update
## pw groups update
Update a group's description
```
pw groups update [flags]
```
### Examples
```
pw groups update --description "Updated description" research-team
```
### Options
```
--description string New group description
-h, --help help for update
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw groups](/docs/cli/pw/groups) - Manage groups and their members
# pw kube
> Source: https://parallelworks.com/docs/cli/pw/kube
## pw kube
Kubernetes commands
### Synopsis
The **pw kube** command group contains commands to interact with Kubernetes resources.
```
pw kube [flags]
```
### Options
```
-h, --help help for kube
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw kube auth](/docs/cli/pw/kube/auth) - Set up cluster configuration
* [pw kube ls](/docs/cli/pw/kube/ls) - List all kubernetes clusters
* [pw kube token](/docs/cli/pw/kube/token) - Token to authenticate with the Kubernetes API
# pw kube auth
> Source: https://parallelworks.com/docs/cli/pw/kube/auth
## pw kube auth
Set up cluster configuration
### Synopsis
The **pw kube auth** command must be followed by a cluster name.
```
pw kube auth [cluster name] [flags]
```
### Examples
```
# Sets up kubectl context for **demo** cluster
pw kube auth demo
```
### Options
```
-h, --help help for auth
--no-context-switch Skip switching to the new context after configuration
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw kube](/docs/cli/pw/kube) - Kubernetes commands
# pw kube ls
> Source: https://parallelworks.com/docs/cli/pw/kube/ls
## pw kube ls
List all kubernetes clusters
```
pw kube ls [flags]
```
### Examples
```
# List all kubernetes clusters
pw kube ls
# List all kubernetes clusters, displayed as json
pw kube ls -o json
# List all kubernetes clusters, displayed as a table
# Tables display Name, total vCPUs, total Memory
pw kube ls -o table
```
### Options
```
-h, --help help for ls
-o, --output string Output format (json, table)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw kube](/docs/cli/pw/kube) - Kubernetes commands
# pw kube token
> Source: https://parallelworks.com/docs/cli/pw/kube/token
## pw kube token
Token to authenticate with the Kubernetes API
### Synopsis
The **pw kube token** command must be followed by a cluster name.
Use this command to get a token to authenticate with the Kubernetes API.
```
pw kube token [clientId] [flags]
```
### Examples
```
# Get a token with the cluster name **demo**
pw kube token demo
```
### Options
```
-h, --help help for token
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw kube](/docs/cli/pw/kube) - Kubernetes commands
# pw lustre
> Source: https://parallelworks.com/docs/cli/pw/lustre
## pw lustre
Manage Lustre filesystems
### Synopsis
The **Lustre** command group lets you create, delete, list, and copy files to your Lustre filesystems.
```
pw lustre [flags]
```
### Options
```
-h, --help help for lustre
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw lustre ls](/docs/cli/pw/lustre/ls) - List all Lustre filesystems
# pw lustre ls
> Source: https://parallelworks.com/docs/cli/pw/lustre/ls
## pw lustre ls
List all Lustre filesystems
```
pw lustre ls [flags]
```
### Examples
```
# List all Lustre filesystems
pw lustre ls
# List all Lustre filesystems, displayed as a table
# Tables display URI, CSP, provisioning status, and CSP URI
pw lustre ls -o table
```
### Options
```
-h, --help help for ls
-o, --output string Output format. One of: table, json, list (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw lustre](/docs/cli/pw/lustre) - Manage Lustre filesystems
# pw marketplace
> Source: https://parallelworks.com/docs/cli/pw/marketplace
## pw marketplace
Manage marketplace items
```
pw marketplace [flags]
```
### Options
```
-h, --help help for marketplace
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw marketplace add-to-account](/docs/cli/pw/marketplace/add-to-account) - Add a marketplace item to your account
* [pw marketplace export](/docs/cli/pw/marketplace/export) - Export marketplace items to bundle directories
* [pw marketplace get](/docs/cli/pw/marketplace/get) - Show a marketplace item
* [pw marketplace icon](/docs/cli/pw/marketplace/icon) - Manage marketplace item icons
* [pw marketplace import](/docs/cli/pw/marketplace/import) - Recreate marketplace items from exported bundles
* [pw marketplace ls](/docs/cli/pw/marketplace/ls) - List marketplace items
* [pw marketplace publish](/docs/cli/pw/marketplace/publish) - Publish a new marketplace item
* [pw marketplace remove-from-account](/docs/cli/pw/marketplace/remove-from-account) - Remove a marketplace workflow reference from your account
* [pw marketplace rm](/docs/cli/pw/marketplace/rm) - Delete a marketplace item
* [pw marketplace slug](/docs/cli/pw/marketplace/slug) - Check whether a marketplace slug is available
* [pw marketplace update](/docs/cli/pw/marketplace/update) - Update a marketplace item's metadata
* [pw marketplace version](/docs/cli/pw/marketplace/version) - Manage marketplace item versions
# pw marketplace add-to-account
> Source: https://parallelworks.com/docs/cli/pw/marketplace/add-to-account
## pw marketplace add-to-account
Add a marketplace item to your account
### Synopsis
Mirrors the marketplace "Add to account" action. Workflows are added as a
reference to the marketplace version; storage and compute items are forked
into an owned resource, which requires **--name**.
```
pw marketplace add-to-account [flags]
```
### Examples
```
# Add the latest version of a workflow to your account
pw marketplace add-to-account my-workflow
# Add a specific workflow version
pw marketplace add-to-account --version v1.0.0 my-workflow
# Fork a storage item into an owned bucket
pw marketplace add-to-account --name my-bucket shared-bucket
```
### Options
```
--convert-to-local For remote workflows, convert to local by fetching the YAML
--ephemeral For storage items, make the forked storage ephemeral
-h, --help help for add-to-account
--name string Name for the forked resource (storage/compute items)
--version string Version of the item to add (default "latest")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
# pw marketplace export
> Source: https://parallelworks.com/docs/cli/pw/marketplace/export
## pw marketplace export
Export marketplace items to bundle directories
### Synopsis
Writes marketplace items to directory bundles (marketplace.yaml, README.md,
icon, and per-version settings) that **pw marketplace import** can recreate on
another platform. With a single item **-o** is the bundle directory; with
several items each bundle is written to **/**. Prompts for any
missing input when run on a terminal.
```
pw marketplace export [slug...] [flags]
```
### Examples
```
# Export an item to ./my-workflow
pw marketplace export my-workflow
# Export to a specific directory, overwriting existing contents
pw marketplace export -o /tmp/my-workflow --force my-workflow
# Export several items as subdirectories of /tmp/bundles
pw marketplace export -o /tmp/bundles my-workflow my-bucket
# Pick the items and destination interactively
pw marketplace export
```
### Options
```
--force Overwrite non-empty destination directories
-h, --help help for export
-o, --output string Destination directory (single item: the bundle dir, default ./; multiple items: parent dir for subdirs, default .)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
# pw marketplace get
> Source: https://parallelworks.com/docs/cli/pw/marketplace/get
## pw marketplace get
Show a marketplace item
```
pw marketplace get [flags]
```
### Examples
```
# Show item details
pw marketplace get my-workflow
# Output as JSON
pw marketplace get -o json my-workflow
# Dump the workflow YAML of the latest version
pw marketplace get --yaml my-workflow
# Dump the markdown readme of a specific version
pw marketplace get --markdown --version v1.0.0 my-workflow
```
### Options
```
-h, --help help for get
--markdown Print the markdown readme
-o, --output string Output format (table, json, yaml)
--version string Version to use with --yaml/--markdown (default "latest")
--yaml Print the workflow YAML definition
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
# pw marketplace icon
> Source: https://parallelworks.com/docs/cli/pw/marketplace/icon
## pw marketplace icon
Manage marketplace item icons
```
pw marketplace icon [flags]
```
### Options
```
-h, --help help for icon
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
* [pw marketplace icon get](/docs/cli/pw/marketplace/icon/get) - Download a marketplace item's icon
* [pw marketplace icon rm](/docs/cli/pw/marketplace/icon/rm) - Remove a marketplace item's icon
* [pw marketplace icon set](/docs/cli/pw/marketplace/icon/set) - Upload a marketplace item's icon
# pw marketplace icon get
> Source: https://parallelworks.com/docs/cli/pw/marketplace/icon/get
## pw marketplace icon get
Download a marketplace item's icon
```
pw marketplace icon get [flags]
```
### Examples
```
# Download an item's icon (file extension follows the image type)
pw marketplace icon get my-workflow
# Download to a specific file
pw marketplace icon get -o ./icon.png my-workflow
```
### Options
```
-h, --help help for get
-o, --output string Destination file (default .)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace icon](/docs/cli/pw/marketplace/icon) - Manage marketplace item icons
# pw marketplace icon rm
> Source: https://parallelworks.com/docs/cli/pw/marketplace/icon/rm
## pw marketplace icon rm
Remove a marketplace item's icon
```
pw marketplace icon rm [flags]
```
### Examples
```
# Remove an item's icon
pw marketplace icon rm my-workflow
```
### Options
```
-h, --help help for rm
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace icon](/docs/cli/pw/marketplace/icon) - Manage marketplace item icons
# pw marketplace icon set
> Source: https://parallelworks.com/docs/cli/pw/marketplace/icon/set
## pw marketplace icon set
Upload a marketplace item's icon
```
pw marketplace icon set [flags]
```
### Examples
```
# Upload an icon image (PNG/JPEG/GIF/WebP)
pw marketplace icon set my-workflow ./icon.png
```
### Options
```
-h, --help help for set
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace icon](/docs/cli/pw/marketplace/icon) - Manage marketplace item icons
# pw marketplace import
> Source: https://parallelworks.com/docs/cli/pw/marketplace/import
## pw marketplace import
Recreate marketplace items from exported bundles
### Synopsis
Reads bundles written by **pw marketplace export** and recreates the items by
publishing each version through the platform's typed marketplace endpoints.
The directory is either a single bundle or a folder whose subdirectories are
bundles (as written by a multi-item export); pointing at a folder imports
several items at once. Items are private unless visibility flags are passed.
Prompts for any missing input when run on a terminal.
```
pw marketplace import [dir] [flags]
```
### Examples
```
# Import a bundle interactively
pw marketplace import ./my-workflow
# Pick items to import from a directory of bundles
pw marketplace import ./backups
# Import under a new slug, visible platform-wide, without prompts
pw marketplace import --slug my-workflow-copy --platform --yes ./my-workflow
```
### Options
```
--group strings Make the item visible to a group (repeatable)
-h, --help help for import
--name string Display name to publish under (default: the bundle's name)
--organization Make the item visible to the publisher's organization
--partner Make the item visible to partner organizations
--platform Make the item visible to all platform users
--slug string Slug to publish under (default: the bundle's slug)
--yes Skip the confirmation prompt
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
# pw marketplace ls
> Source: https://parallelworks.com/docs/cli/pw/marketplace/ls
## pw marketplace ls
List marketplace items
```
pw marketplace ls [flags]
```
### Examples
```
# List all marketplace items
pw marketplace ls
# List only items you published
pw marketplace ls --mine
# List as plain slugs (one per line)
pw marketplace ls -o list
# Output as JSON
pw marketplace ls -o json
```
### Options
```
--featured Only featured items
-h, --help help for ls
--mine Only items published by you
--modifiable Only items you can modify
--org Only items published as your organization
-o, --output string Output format (table, json, list)
--verified Only verified items
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
# pw marketplace publish
> Source: https://parallelworks.com/docs/cli/pw/marketplace/publish
## pw marketplace publish
Publish a new marketplace item
```
pw marketplace publish [flags]
```
### Examples
```
# Publish a local workflow from a YAML file (private by default)
pw marketplace publish --name "My Workflow" --slug my-workflow --yaml ./workflow.yaml
# Publish a remote workflow from a git repository, visible platform-wide
pw marketplace publish --name "My Workflow" --slug my-workflow --repo https://github.com/org/repo --branch main --platform
# Publish a storage item from a JSON file of publish-body fields
pw marketplace publish --subtype aws-bucket --name "My Bucket" --slug my-bucket --json ./bucket.json
# Publish a storage item from stdin
echo '{"region":"us-east-1","versioning":true}' | pw marketplace publish --subtype aws-bucket --name "My Bucket" --slug my-bucket --json -
```
### Options
```
--branch string Git branch for a remote workflow
--description string Short summary of the item
--featured Mark as featured (platform admins only)
--group strings Make the item visible to a group (repeatable)
-h, --help help for publish
--json string Path to a JSON file with the subtype's publish-body fields, or - for stdin
--markdown string Path to a markdown file used as the item readme
--name string Display name on the marketplace
--organization Make the item visible to the publisher's organization
-o, --output string Output format (json)
--partner Make the item visible to partner organizations
--platform Make the item visible to all platform users
--published-as-org Publish under the organization display name (org admins only)
--readme string Path to the README within the repo
--repo string Git repository URL for a remote workflow
--slug string URL-friendly identifier
--subtype string Item subtype for non-workflow publishing; one of: aws-bucket, aws-disk, aws-efs, aws-lustre, aws-slurm, azure-azfiles, azure-bucket, azure-disk, azure-managedlustre, azure-netappfiles, azure-slurm, existing, google-bucket, google-disk, google-filestore, google-managedlustre, google-slurm, local, openstack-slurm, oracle-bucket, oracle-oraclefs, oracle-slurm, remote
--thumbnail string Path to the thumbnail image within the repo
--verified Mark as verified (platform admins only)
--version string Initial version label (must start with v) (default "v1.0.0")
--workflow-yaml string Path to the workflow YAML within the repo
--yaml string Path to a local workflow YAML file
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
# pw marketplace remove-from-account
> Source: https://parallelworks.com/docs/cli/pw/marketplace/remove-from-account
## pw marketplace remove-from-account
Remove a marketplace workflow reference from your account
### Synopsis
Removes a workflow's account-version reference. Forked storage and compute
resources are owned resources; delete them under **pw storage** or
**pw compute** instead.
```
pw marketplace remove-from-account [flags]
```
### Examples
```
# Remove the latest version of a workflow from your account
pw marketplace remove-from-account my-workflow
# Remove a specific workflow version
pw marketplace remove-from-account --version v1.0.0 my-workflow
```
### Options
```
-h, --help help for remove-from-account
--version string Version of the item to remove (default "latest")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
# pw marketplace rm
> Source: https://parallelworks.com/docs/cli/pw/marketplace/rm
## pw marketplace rm
Delete a marketplace item
```
pw marketplace rm [flags]
```
### Examples
```
# Delete an item (asks for confirmation)
pw marketplace rm my-workflow
# Delete without confirmation
pw marketplace rm --yes my-workflow
```
### Options
```
-h, --help help for rm
--yes Skip the confirmation prompt
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
# pw marketplace slug
> Source: https://parallelworks.com/docs/cli/pw/marketplace/slug
## pw marketplace slug
Check whether a marketplace slug is available
```
pw marketplace slug [flags]
```
### Examples
```
# Check slug availability (exits nonzero if taken)
pw marketplace slug my-new-item
```
### Options
```
-h, --help help for slug
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
# pw marketplace update
> Source: https://parallelworks.com/docs/cli/pw/marketplace/update
## pw marketplace update
Update a marketplace item's metadata
### Synopsis
Updates only the fields whose flags are passed. The visibility flags
(**--platform**, **--partner**, **--organization**, **--group**) are the
exception: passing any of them replaces the item's visibility as a whole,
so include every audience the item should keep.
```
pw marketplace update [flags]
```
### Examples
```
# Rename an item
pw marketplace update --name "New Name" my-workflow
# Make an item visible to the whole platform
pw marketplace update --platform my-workflow
# Make an item private again
pw marketplace update --platform=false --partner=false --organization=false --group= my-workflow
```
### Options
```
--description string Short summary of the item
--featured Mark as featured (platform admins only)
--group strings Make the item visible to a group (repeatable)
-h, --help help for update
--markdown string Path to a markdown file used as the item readme
--name string Display name on the marketplace
--organization Make the item visible to the publisher's organization
-o, --output string Output format (json)
--partner Make the item visible to partner organizations
--platform Make the item visible to all platform users
--published-as-org Publish under the organization display name (org admins only)
--slug string New URL-friendly identifier
--verified Mark as verified (platform admins only)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
# pw marketplace version
> Source: https://parallelworks.com/docs/cli/pw/marketplace/version
## pw marketplace version
Manage marketplace item versions
```
pw marketplace version [flags]
```
### Options
```
-h, --help help for version
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace](/docs/cli/pw/marketplace) - Manage marketplace items
* [pw marketplace version ls](/docs/cli/pw/marketplace/version/ls) - List versions of a marketplace item
* [pw marketplace version publish](/docs/cli/pw/marketplace/version/publish) - Publish a new version of a marketplace item
* [pw marketplace version rm](/docs/cli/pw/marketplace/version/rm) - Remove a version from a marketplace item
# pw marketplace version ls
> Source: https://parallelworks.com/docs/cli/pw/marketplace/version/ls
## pw marketplace version ls
List versions of a marketplace item
```
pw marketplace version ls [flags]
```
### Examples
```
# List versions of an item
pw marketplace version ls my-workflow
# List as plain version labels (one per line)
pw marketplace version ls -o list my-workflow
# Output versions with their settings as JSON
pw marketplace version ls -o json my-workflow
```
### Options
```
-h, --help help for ls
-o, --output string Output format (table, json, list)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace version](/docs/cli/pw/marketplace/version) - Manage marketplace item versions
# pw marketplace version publish
> Source: https://parallelworks.com/docs/cli/pw/marketplace/version/publish
## pw marketplace version publish
Publish a new version of a marketplace item
```
pw marketplace version publish [flags]
```
### Examples
```
# Add a local workflow version from a YAML file
pw marketplace version publish --version v1.1.0 --yaml ./workflow.yaml my-workflow
# Replace an existing version's variables
pw marketplace version publish --version v1.1.0 --replace --yaml ./workflow.yaml my-workflow
# Add a storage/compute version from a JSON file of version fields
pw marketplace version publish --version v2.0.0 --json ./bucket.json my-bucket
```
### Options
```
--branch string Git branch for a remote workflow
-h, --help help for publish
--json string Path to a JSON file with the subtype's version fields, or - for stdin
-o, --output string Output format (json)
--readme string Path to the README within the repo
--replace Replace an existing version's variables instead of adding a new version
--repo string Git repository URL for a remote workflow
--thumbnail string Path to the thumbnail image within the repo
--version string Version label to add (must start with v)
--workflow-yaml string Path to the workflow YAML within the repo
--yaml string Path to a local workflow YAML file
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace version](/docs/cli/pw/marketplace/version) - Manage marketplace item versions
# pw marketplace version rm
> Source: https://parallelworks.com/docs/cli/pw/marketplace/version/rm
## pw marketplace version rm
Remove a version from a marketplace item
```
pw marketplace version rm [flags]
```
### Examples
```
# Remove a version (the item must keep at least one)
pw marketplace version rm my-workflow v1.0.0
# Remove without confirmation
pw marketplace version rm --yes my-workflow v1.0.0
```
### Options
```
-h, --help help for rm
--yes Skip the confirmation prompt
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw marketplace version](/docs/cli/pw/marketplace/version) - Manage marketplace item versions
# pw nfs
> Source: https://parallelworks.com/docs/cli/pw/nfs
## pw nfs
Manage NFS storages
### Synopsis
The **NFS** command group lets you manage your NFS storages.
```
pw nfs [flags]
```
### Options
```
-h, --help help for nfs
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw nfs ls](/docs/cli/pw/nfs/ls) - List all NFS Storages
# pw nfs ls
> Source: https://parallelworks.com/docs/cli/pw/nfs/ls
## pw nfs ls
List all NFS Storages
```
pw nfs ls [flags]
```
### Examples
```
# List all NFS Storages
pw nfs ls
# List all NFS Storages, displayed as a table
# Tables display URI, CSP, provisioning status, type, region, and tags
pw nfs ls -o table
```
### Options
```
-h, --help help for ls
-o, --output string Output format. One of: table, json, list (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw nfs](/docs/cli/pw/nfs) - Manage NFS storages
# pw orgs
> Source: https://parallelworks.com/docs/cli/pw/orgs
## pw orgs
Manage organizations
```
pw orgs [flags]
```
### Options
```
-h, --help help for orgs
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw orgs delete](/docs/cli/pw/orgs/delete) - Delete an organization
* [pw orgs ls](/docs/cli/pw/orgs/ls) - List organizations
# pw orgs delete
> Source: https://parallelworks.com/docs/cli/pw/orgs/delete
## pw orgs delete
Delete an organization
### Synopsis
The **pw orgs delete** command deletes an organization and all its users, groups, and settings.
This action is irreversible. You will be prompted to type the organization name to confirm.
Use **-f** to skip the confirmation prompt.
```
pw orgs delete [flags]
```
### Examples
```
# Delete an organization
pw orgs delete my-org
# Skip confirmation
pw orgs delete -f my-org
```
### Options
```
-f, --force Skip confirmation prompt
-h, --help help for delete
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw orgs](/docs/cli/pw/orgs) - Manage organizations
# pw orgs ls
> Source: https://parallelworks.com/docs/cli/pw/orgs/ls
## pw orgs ls
List organizations
### Synopsis
The **pw orgs ls** command lists all organizations accessible to you.
```
pw orgs ls [flags]
```
### Examples
```
# List all organizations
pw orgs ls
# List as JSON
pw orgs ls -o json
# List names only
pw orgs ls -o list
```
### Options
```
-h, --help help for ls
-o, --output string Output format (table, json, list) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw orgs](/docs/cli/pw/orgs) - Manage organizations
# pw sessions
> Source: https://parallelworks.com/docs/cli/pw/sessions
## pw sessions
Manage sessions
```
pw sessions [flags]
```
### Options
```
-h, --help help for sessions
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw sessions connect](/docs/cli/pw/sessions/connect) - Connect to a running session
* [pw sessions create](/docs/cli/pw/sessions/create) - Create a new session on a remote resource
* [pw sessions ls](/docs/cli/pw/sessions/ls) - List all sessions
* [pw sessions open](/docs/cli/pw/sessions/open) - Open a session in the browser
* [pw sessions stop](/docs/cli/pw/sessions/stop) - Stop and delete a session
# pw sessions connect
> Source: https://parallelworks.com/docs/cli/pw/sessions/connect
## pw sessions connect
Connect to a running session
### Synopsis
Connect to a running session by name. The session must already be running.
For desktop sessions, this creates a local TCP listener that proxies
traffic to the session's WebSocket endpoint.
For tunnel sessions, this creates an SSH port forward to the session's remote
host and port.
VS Code sessions are not supported by connect. Use **pw session open** to
open in the browser or **pw vscode** for local VS Code.
Press Ctrl+C to disconnect. This does not stop the session.
```
pw sessions connect [flags]
```
### Examples
```
# Connect to a desktop session
pw session connect my-desktop
# Connect to a tunnel session on a specific local port
pw session connect --port 8080 my-tunnel
```
### Options
```
-h, --help help for connect
--port int Local port to use (0 = auto-select)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw sessions](/docs/cli/pw/sessions) - Manage sessions
# pw sessions create
> Source: https://parallelworks.com/docs/cli/pw/sessions/create
## pw sessions create
Create a new session on a remote resource
### Synopsis
The **pw session create** command creates a new session on a remote resource.
Supported session types:
- **desktop** - VNC desktop session
- **vscode** - VS Code server session
- **tunnel** - TCP port tunnel (requires --remote-port)
By default, the command returns immediately after creating the session.
Use **--wait** to wait for the session to be running before exiting.
**--open** and **--connect** imply **--wait**.
Resource names can be specified in the following formats:
- **workspace** or **user-workspace** - your user workspace
- **pw://username/name** - full format with explicit username
- **pw://name** - managed cluster by name in your organization
- **name** - short format where username defaults to your username
By default a session runs on the cluster's login node. To run it on a compute
node instead, either schedule a new worker with **--environment**, or reuse a
worker you already have with **--worker**:
- **--environment** submits a scheduler job for a dedicated worker and starts
the session on it once the job runs. Pass **--param** to set the
environment's scheduling parameters, and run **pw environments get** to see
which parameters it accepts. Scheduling is queued, so pair this with
**--wait**.
- **--worker** starts the session on an existing connected worker, as listed
by **pw workers ls**. This skips the queue.
```
pw sessions create --type TYPE [flags]
```
### Examples
```
# Create a desktop session on your user workspace
pw session create --type desktop workspace
# Create a desktop session on a resource
pw session create --type desktop my-cluster
# Create a VS Code session
pw session create --type vscode my-cluster
# Create a VS Code session opening a specific directory
pw session create --type vscode --directory '~/projects' my-cluster
# Create a tunnel session forwarding a remote port
pw session create --type tunnel --remote-port 8080 my-cluster
# Create and immediately open in the browser
pw session create --type desktop --open my-cluster
# Create a session with a custom name
pw session create --type tunnel --name my-tunnel --remote-port 8080 my-cluster
# Create and immediately connect (port forward)
pw session create --type tunnel --connect --port 8080 --remote-port 3000 my-cluster
# Create a public session anyone can open without logging in
pw session create --type desktop --public my-cluster
# Schedule a desktop session onto a compute environment
pw session create --type desktop --environment gpu-large --wait my-hpc
# Schedule with environment parameters
pw session create --type desktop --environment gpu-large --param numNodes=2 --wait my-hpc
# Start a session on a worker that is already running
pw session create --type desktop --worker 60c72b2f9b1e8d001c8e4f3a my-hpc
```
### Options
```
--connect Connect (port forward) after creation (desktop and tunnel only, implies --wait)
--directory string Directory to open in VS Code
--environment string Schedule the session onto a compute environment, by name or ID
-h, --help help for create
--name string Custom session name (default: _)
--open Open the session in the browser after creation (implies --wait)
--param stringArray Scheduling parameter for --environment as key=value (repeatable)
--port int Local port for --connect (0 = auto-select)
--public Make the session publicly accessible: anyone with the link can open it without logging in. Requires your organization to allow public sessions.
--remote-host string Remote host for tunnel type (default "localhost")
--remote-port int Remote port (required for tunnel type)
--type string Session type: desktop, vscode, tunnel (required)
--wait Wait for the session to be running before exiting
--worker string Run the session on an existing compute worker, by ID
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw sessions](/docs/cli/pw/sessions) - Manage sessions
# pw sessions ls
> Source: https://parallelworks.com/docs/cli/pw/sessions/ls
## pw sessions ls
List all sessions
```
pw sessions ls [flags]
```
### Examples
```
# List all sessions
pw session ls
# List all sessions, displayed as a table
# Tables display URI, Status, Local Port, Remote Host, Remote Port, and Workflow Run
pw sessions ls -o table
# List only desktop sessions
pw session ls --type desktop
```
### Options
```
-h, --help help for ls
-o, --output string Output format (json, table)
-t, --type string Filter by session type (desktop, vscode, tunnel)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw sessions](/docs/cli/pw/sessions) - Manage sessions
# pw sessions open
> Source: https://parallelworks.com/docs/cli/pw/sessions/open
## pw sessions open
Open a session in the browser
### Synopsis
Open a running session in your default browser.
For desktop sessions, opens the VNC viewer in the browser.
For VS Code sessions, opens the VS Code server in the browser.
For tunnel sessions, opens the session page in the browser.
The session name can be found using **pw session ls**.
```
pw sessions open [flags]
```
### Examples
```
# Open a desktop session in the browser
pw session open my-desktop
# Open a vscode session in the browser
pw session open my-vscode
```
### Options
```
-h, --help help for open
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw sessions](/docs/cli/pw/sessions) - Manage sessions
# pw sessions stop
> Source: https://parallelworks.com/docs/cli/pw/sessions/stop
## pw sessions stop
Stop and delete a session
### Synopsis
The **pw session stop** command stops a running session and deletes it.
The session name can be found using **pw session ls**.
```
pw sessions stop [flags]
```
### Examples
```
# Stop a desktop session
pw session stop desktop_1771523513
# Stop a tunnel session
pw session stop tunnel_1771523513
```
### Options
```
-h, --help help for stop
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw sessions](/docs/cli/pw/sessions) - Manage sessions
# pw ssh
> Source: https://parallelworks.com/docs/cli/pw/ssh
## pw ssh
Initiate an SSH connection to a resource
### Synopsis
The **pw ssh** command initiates an SSH connection to a specific compute resource. The resource has to be running, and you must have SSH access to it.
Resource names can be specified in the following formats:
- **pw://username/name** - full format with explicit username
- **pw://name** - managed cluster by name in your organization
- **name** - short format where username defaults to your username
- **worker/id** - compute node running one of your workers, as listed by **pw workers ls**
```
pw ssh [command] [flags]
```
### Examples
```
# Interactively connect to a resource named 'my-resource' owned by you
pw ssh my-resource
# Interactively connect to a resource owned by another user
pw ssh pw://Jake.Thayne/my-resource
# Interactively connect to a managed cluster in your organization
pw ssh my-managed-cluster
pw ssh pw://my-managed-cluster
# Interactively connect to your user workspace
pw ssh workspace
# Interactively connect to the compute node running one of your workers
pw ssh worker/60c72b2f9b1e8d001c8e4f3a
# Run the "hostname" command on a resource and exit
pw ssh my-resource hostname
# Run the "hostname" command on your user workspace and exit
pw ssh workspace hostname
# Connect to a node via a pw:// jump host (username defaults to resource username)
pw ssh -J pw://Jake.Thayne/my-cluster 10.0.1.5
# Connect to a node via a jump host with an explicit username
pw ssh -J pw://Jake.Thayne/my-cluster alice@10.0.1.5
# Run as a ProxyCommand for SSH
ssh -i ~/.ssh/pwcli -o ProxyCommand="pw ssh --proxy-command %h" user@my-resource
ssh -i ~/.ssh/pwcli -o ProxyCommand="pw ssh --proxy-command %h" user@pw://Jake.Thayne/my-resource
ssh -i ~/.ssh/pwcli -o ProxyCommand="pw ssh --proxy-command %h" user@workspace
# Run as a ProxyCommand for SSH, with port forward
ssh -i ~/.ssh/pwcli -L 8080:localhost:80 -o ProxyCommand="pw ssh --proxy-command %h" user@my-resource
ssh -i ~/.ssh/pwcli -R 80:localhost:8000 -o ProxyCommand="pw ssh --proxy-command %h" user@workspace
# Run as a ProxyCommand for SCP
scp -i ~/.ssh/pwcli -o ProxyCommand="pw ssh --proxy-command %h" file.txt user@my-resource:/home/user/file.txt
scp -i ~/.ssh/pwcli -o ProxyCommand="pw ssh --proxy-command %h" file.txt user@workspace:/home/user/file.txt
```
### Options
```
-h, --help help for ssh
-J, --jump string Connect to the target via a pw:// jump host (similar to ssh -J)
--keepalive int Interval in seconds between keepalive messages; an unresponsive connection is closed (0 to disable) (default 30)
-L, --local stringArray Forward local [bind_address:]port to remote host:hostport
--proxy-command Run as a proxy command for SSH or SCP
-R, --remote stringArray Forward remote [bind_address:]port to local host:hostport
-X, --x11 Enable X11 forwarding
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
# pw ssh-public-keys
> Source: https://parallelworks.com/docs/cli/pw/ssh-public-keys
## pw ssh-public-keys
Get the SSH public keys for a user
### Synopsis
The **pw ssh-public-keys** command retrieves the SSH public keys for a specific user.
```
pw ssh-public-keys [flags]
```
### Options
```
-h, --help help for ssh-public-keys
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
# pw subdomains
> Source: https://parallelworks.com/docs/cli/pw/subdomains
## pw subdomains
Reserve session subdomains
### Synopsis
Reserve session subdomains so no other user can claim them. A reserved
subdomain stays yours even while no session is serving it — use it later
with **pw endpoints --subdomain NAME** or when creating a session.
Requires the platform to have a sessions domain registered.
```
pw subdomains [flags]
```
### Options
```
-h, --help help for subdomains
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw subdomains list](/docs/cli/pw/subdomains/list) - List your reserved subdomains
* [pw subdomains release](/docs/cli/pw/subdomains/release) - Release a reserved subdomain
* [pw subdomains reserve](/docs/cli/pw/subdomains/reserve) - Reserve a subdomain for your user
# pw subdomains list
> Source: https://parallelworks.com/docs/cli/pw/subdomains/list
## pw subdomains list
List your reserved subdomains
```
pw subdomains list [flags]
```
### Options
```
-h, --help help for list
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw subdomains](/docs/cli/pw/subdomains) - Reserve session subdomains
# pw subdomains release
> Source: https://parallelworks.com/docs/cli/pw/subdomains/release
## pw subdomains release
Release a reserved subdomain
```
pw subdomains release [flags]
```
### Options
```
-h, --help help for release
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw subdomains](/docs/cli/pw/subdomains) - Reserve session subdomains
# pw subdomains reserve
> Source: https://parallelworks.com/docs/cli/pw/subdomains/reserve
## pw subdomains reserve
Reserve a subdomain for your user
### Synopsis
Reserve a subdomain: a label (my-app), which lands on the platform's default
sessions domain, or the full host under any registered sessions domain
(my-app.).
```
pw subdomains reserve [flags]
```
### Examples
```
# Reserve a label on the default sessions domain
pw subdomains reserve my-app
# Reserve the full host under a specific sessions domain
pw subdomains reserve my-app.sessions.example.com
```
### Options
```
-h, --help help for reserve
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw subdomains](/docs/cli/pw/subdomains) - Reserve session subdomains
# pw upgrade
> Source: https://parallelworks.com/docs/cli/pw/upgrade
## pw upgrade
Update the version of the CLI
### Synopsis
The **pw upgrade** command updates the current version of the PW CLI to the latest from the platform that it is currently authenticated to.
Pass **--canary** to upgrade to the canary build instead.
```
pw upgrade [flags]
```
### Options
```
--canary Upgrade to the canary build instead of the authenticated platform's version
-h, --help help for upgrade
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
# pw users
> Source: https://parallelworks.com/docs/cli/pw/users
## pw users
Manage organization users
```
pw users [flags]
```
### Options
```
-h, --help help for users
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw users delete](/docs/cli/pw/users/delete) - Delete a user from the organization
* [pw users ls](/docs/cli/pw/users/ls) - List organization users
* [pw users reset-onboarding](/docs/cli/pw/users/reset-onboarding) - Reset onboarding state for one or more users
# pw users delete
> Source: https://parallelworks.com/docs/cli/pw/users/delete
## pw users delete
Delete a user from the organization
### Synopsis
The **pw users delete** command deletes a user and cleans up all their resources.
By default it uses the organization from your current context.
Use **--org** to target a different organization.
You will be prompted to type the username to confirm deletion.
Use **-f** to skip the confirmation prompt.
```
pw users delete [flags]
```
### Examples
```
# Delete a user
pw users delete jake.thayne
# Delete a user from a specific organization
pw users delete --org my-org jake.thayne
# Skip confirmation
pw users delete -f jake.thayne
```
### Options
```
-f, --force Skip confirmation prompt
-h, --help help for delete
--org string Target organization (defaults to current context)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw users](/docs/cli/pw/users) - Manage organization users
# pw users ls
> Source: https://parallelworks.com/docs/cli/pw/users/ls
## pw users ls
List organization users
### Synopsis
The **pw users ls** command lists all users in the organization.
By default it uses the organization from your current context.
Use **--org** to target a different organization.
```
pw users ls [flags]
```
### Examples
```
# List all users
pw users ls
# List users in a specific organization
pw users ls --org my-org
# List as JSON
pw users ls -o json
# Search for a user
pw users ls --search john
# List only active users
pw users ls --active true
```
### Options
```
--active string Filter by active status (all, true, false)
-h, --help help for ls
--limit int Maximum number of users to return (default 50)
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json, list) (default "table")
--search string Filter by username, email, or name
--sort-by string Sort by field (username, email, lastLogin, createdAt)
--sort-dir string Sort direction (asc, desc)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw users](/docs/cli/pw/users) - Manage organization users
# pw users reset-onboarding
> Source: https://parallelworks.com/docs/cli/pw/users/reset-onboarding
## pw users reset-onboarding
Reset onboarding state for one or more users
### Synopsis
The **pw users reset-onboarding** command marks the given users as needing
to complete onboarding again. Requires the **org:users** role in the target
organization (platform admins also qualify).
By default it uses the organization from your current context.
Use **--org** to target a different organization.
```
pw users reset-onboarding [username...] [flags]
```
### Examples
```
# Reset one user
pw users reset-onboarding alice
# Reset multiple users in a specific organization
pw users reset-onboarding --org my-org alice bob
# Skip confirmation
pw users reset-onboarding -f alice
# Output as JSON
pw users reset-onboarding -o json alice bob
```
### Options
```
-f, --force Skip confirmation prompt
-h, --help help for reset-onboarding
--org string Target organization (defaults to current context)
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw users](/docs/cli/pw/users) - Manage organization users
# pw variables
> Source: https://parallelworks.com/docs/cli/pw/variables
## pw variables
Manage your user variables
```
pw variables [flags]
```
### Examples
```
# Set a secret variable — value is prompted (hidden), keeping it out of shell history
pw variables -k GITHUB_TOKEN
# Set a public (non-secret) variable inline
pw variables --public -k REGION --value us-east-1
# Fully interactive (prompts for key, secret, and value)
pw variables
# Pass a secret value inline (NOTE: visible in shell history — prefer the prompt above)
pw variables -k GITHUB_TOKEN --value ghp_xxx
# List your variables
pw variables list
```
### Options
```
-h, --help help for variables
-k, --key string Variable key
--public Make the variable public (non-secret); variables are secret by default
--value string Variable value (omit to be prompted; inline secret values are visible in shell history)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw variables delete](/docs/cli/pw/variables/delete) - Delete a user variable
* [pw variables list](/docs/cli/pw/variables/list) - List your user variables
# pw variables delete
> Source: https://parallelworks.com/docs/cli/pw/variables/delete
## pw variables delete
Delete a user variable
```
pw variables delete [flags]
```
### Examples
```
# Delete a variable
pw variables delete GITHUB_TOKEN
```
### Options
```
-h, --help help for delete
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw variables](/docs/cli/pw/variables) - Manage your user variables
# pw variables list
> Source: https://parallelworks.com/docs/cli/pw/variables/list
## pw variables list
List your user variables
```
pw variables list [flags]
```
### Examples
```
# List your variables
pw variables list
# Output as JSON
pw variables list -o json
```
### Options
```
-h, --help help for list
-o, --output string Output format (interactive, json) (default "interactive")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw variables](/docs/cli/pw/variables) - Manage your user variables
# pw version
> Source: https://parallelworks.com/docs/cli/pw/version
## pw version
Show detailed CLI version information
```
pw version [flags]
```
### Options
```
-h, --help help for version
-o, --output string Output format (text, json) (default "text")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
# pw vscode
> Source: https://parallelworks.com/docs/cli/pw/vscode
## pw vscode
Open VS Code connected to a remote resource
### Synopsis
Open Visual Studio Code connected to a remote resource via SSH.
This configures VS Code's Remote-SSH extension to connect through
the Parallel Works platform and launches VS Code.
Requires the **code** CLI on your PATH and the Remote-SSH extension
installed in VS Code.
By default VS Code opens on the cluster's login node. To open it on a
compute node instead, pick one of:
- **--environment** schedules a new worker on a compute environment and
opens VS Code on its node once the scheduler starts it. Pass **--param**
to set the environment's scheduling parameters, and run
**pw environments get** to see which parameters it accepts.
- **--worker** opens on the node of a worker you already have, as listed by
**pw workers ls**. This skips the queue.
- **--jump-node** opens on a compute node by hostname.
Worker sessions connect through the worker's own SSH server on the compute
node, authenticated by your platform-registered key. Clusters whose agent is
too old to run one, and **--jump-node**, instead go through the login node to
the node's system SSH daemon, which must accept your key on its own.
A worker scheduled this way outlives the editor. Release it with
**pw workers delete** when you are done.
```
pw vscode [flags] [path]
```
### Examples
```
# Open VS Code on a resource
pw vscode my-cluster
# Open VS Code in a specific directory
pw vscode my-cluster /home/user/project
# Open VS Code on another user's resource
pw vscode otheruser/their-cluster
# Schedule a compute node and open VS Code on it
pw vscode --environment gpu-large my-hpc
# Schedule with environment parameters
pw vscode --environment gpu-large --param numNodes=2 my-hpc
# Open VS Code on the compute node running a worker
pw vscode --worker 60c72b2f9b1e8d001c8e4f3a my-hpc
# Open VS Code on a compute node by hostname, via the login node
pw vscode --jump-node node-0002 my-hpc
```
### Options
```
--environment string Schedule a new worker on this compute environment, by name or ID, and open on its node
-h, --help help for vscode
--jump-node string Open on this compute node by hostname, jumping through the login node to the node's system SSH daemon
--param stringArray Scheduling parameter for --environment as key=value (repeatable)
--partition string Scheduler partition for a new worker, for use without --environment
--worker string Open on the compute node running this worker, by ID
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
# pw workers
> Source: https://parallelworks.com/docs/cli/pw/workers
## pw workers
Manage compute workers
### Synopsis
The **pw workers** command group has commands for managing compute workers. A
worker is a scheduler job that runs on a cluster's compute nodes and hosts
sessions.
Workers are normally created for you when you schedule a session onto an
environment with **pw session create --environment**. Create one directly to
pre-provision capacity, then start sessions on it with
**pw session create --worker**.
Workers belong to you rather than to a cluster, and are referenced by ID as
shown by **pw workers ls**.
```
pw workers [flags]
```
### Options
```
-h, --help help for workers
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw workers create](/docs/cli/pw/workers/create) - Pre-provision a compute worker
* [pw workers delete](/docs/cli/pw/workers/delete) - Stop and delete a compute worker
* [pw workers get](/docs/cli/pw/workers/get) - Get details of a compute worker
* [pw workers ls](/docs/cli/pw/workers/ls) - List your compute workers
# pw workers create
> Source: https://parallelworks.com/docs/cli/pw/workers/create
## pw workers create
Pre-provision a compute worker
### Synopsis
The **pw workers create** command submits a scheduler job that pre-provisions a
compute worker, so sessions can start on it without waiting in the queue. Start
a session on it with **pw session create --worker**.
The cluster can be given as **pw://user/cluster**, **pw://cluster** or
**cluster**, where an omitted user defaults to your username.
Pass **--environment** to schedule the worker onto an environment, which
determines the partition and validates **--param** values against the
environment's schema. Run **pw environments get** to see which parameters an
environment accepts.
Scheduling is queued, so the command returns as soon as the job is submitted.
Use **--wait** to wait for the worker's job to run and its tunnel to connect.
```
pw workers create [flags]
```
### Examples
```
# Pre-provision a worker on an environment
pw workers create --environment gpu-large my-hpc
# Request two nodes for a longer wall time
pw workers create --environment gpu-large --param numNodes=2 --param walltime=04:00:00 my-hpc
# Pre-provision on a partition directly, without an environment
pw workers create --partition gpu my-hpc
# Wait for the worker to be ready
pw workers create --environment gpu-large --wait my-hpc
```
### Options
```
--environment string Environment to schedule the worker onto, by name or ID
-h, --help help for create
--param stringArray Scheduling parameter as key=value (repeatable)
--partition string Scheduler partition to use when no environment is given
--wait Wait for the worker to connect before exiting
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workers](/docs/cli/pw/workers) - Manage compute workers
# pw workers delete
> Source: https://parallelworks.com/docs/cli/pw/workers/delete
## pw workers delete
Stop and delete a compute worker
### Synopsis
The **pw workers delete** command stops a compute worker's scheduler job and
deletes it. Any sessions running on the worker stop with it.
Worker IDs are shown by **pw workers ls**.
```
pw workers delete [flags]
```
### Examples
```
# Delete a worker
pw workers delete 60c72b2f9b1e8d001c8e4f3a
```
### Options
```
-h, --help help for delete
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workers](/docs/cli/pw/workers) - Manage compute workers
# pw workers get
> Source: https://parallelworks.com/docs/cli/pw/workers/get
## pw workers get
Get details of a compute worker
### Synopsis
The **pw workers get** command shows a compute worker's status, the environment
it was scheduled onto, and the scheduler job backing it.
Worker IDs are shown by **pw workers ls**.
```
pw workers get [flags]
```
### Examples
```
# Get a worker
pw workers get 60c72b2f9b1e8d001c8e4f3a
# Get as JSON
pw workers get -o json 60c72b2f9b1e8d001c8e4f3a
```
### Options
```
-h, --help help for get
-o, --output string Output format (table, json) (default "table")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workers](/docs/cli/pw/workers) - Manage compute workers
# pw workers ls
> Source: https://parallelworks.com/docs/cli/pw/workers/ls
## pw workers ls
List your compute workers
### Synopsis
The **pw workers ls** command lists your compute workers across all clusters.
Use **--cluster** to list only the workers on one cluster. The cluster can be
given as **pw://user/cluster**, **pw://cluster** or **cluster**, where an
omitted user defaults to your username.
```
pw workers ls [flags]
```
### Examples
```
# List all of your workers
pw workers ls
# List only connected workers
pw workers ls --status connected
# List the workers on one cluster
pw workers ls --cluster my-hpc
# List as JSON
pw workers ls -o json
```
### Options
```
--cluster string Filter by cluster
-h, --help help for ls
--limit int Maximum number of workers to return (default 100, max 500)
-o, --output string Output format (table, json, list) (default "table")
--skip int Number of workers to skip for pagination
--status string Filter by status (pending, queued, starting, connected, stopping, stopped, error)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workers](/docs/cli/pw/workers) - Manage compute workers
# pw workflows
> Source: https://parallelworks.com/docs/cli/pw/workflows
## pw workflows
Manage workflows
```
pw workflows [flags]
```
### Options
```
-h, --help help for workflows
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw](/docs/cli/pw) - The Parallel Works ACTIVATE CLI
* [pw workflows create](/docs/cli/pw/workflows/create) - Create a new workflow
* [pw workflows delete](/docs/cli/pw/workflows/delete) - Delete a workflow
* [pw workflows get](/docs/cli/pw/workflows/get) - Get details of a workflow
* [pw workflows ls](/docs/cli/pw/workflows/ls) - List all workflows
* [pw workflows run](/docs/cli/pw/workflows/run) - Run a saved workflow or a local YAML file
* [pw workflows runs](/docs/cli/pw/workflows/runs) - Manage workflow runs
* [pw workflows update](/docs/cli/pw/workflows/update) - Update a workflow
# pw workflows create
> Source: https://parallelworks.com/docs/cli/pw/workflows/create
## pw workflows create
Create a new workflow
```
pw workflows create [flags]
```
### Examples
```
# Create a local workflow with default template
pw workflows create my-workflow
# Create a workflow from a YAML file
pw workflows create --yaml workflow.yaml my-workflow
# Create a workflow with a display name
pw workflows create --display-name "My Workflow" my-workflow
```
### Options
```
--description string Description of the workflow
--display-name string Display name for the workflow
-h, --help help for create
-o, --output string Output format (json)
--yaml string Path to YAML file for workflow definition
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows](/docs/cli/pw/workflows) - Manage workflows
# pw workflows delete
> Source: https://parallelworks.com/docs/cli/pw/workflows/delete
## pw workflows delete
Delete a workflow
```
pw workflows delete [flags]
```
### Examples
```
# Delete a workflow
pw workflows delete my-workflow
```
### Options
```
-h, --help help for delete
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows](/docs/cli/pw/workflows) - Manage workflows
# pw workflows get
> Source: https://parallelworks.com/docs/cli/pw/workflows/get
## pw workflows get
Get details of a workflow
```
pw workflows get [flags]
```
### Examples
```
# Get workflow details
pw workflows get my-workflow
# Get workflow details as JSON
pw workflows get -o json my-workflow
# Get workflow YAML definition
pw workflows get -o yaml my-workflow
```
### Options
```
-h, --help help for get
-o, --output string Output format (json, yaml)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows](/docs/cli/pw/workflows) - Manage workflows
# pw workflows ls
> Source: https://parallelworks.com/docs/cli/pw/workflows/ls
## pw workflows ls
List all workflows
```
pw workflows ls [flags]
```
### Examples
```
# List all workflows
pw workflows ls
# List as plain names (one per line)
pw workflows ls -o list
# Output as JSON
pw workflows ls -o json
```
### Options
```
-h, --help help for ls
-o, --output string Output format (json, list)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows](/docs/cli/pw/workflows) - Manage workflows
# pw workflows run
> Source: https://parallelworks.com/docs/cli/pw/workflows/run
## pw workflows run
Run a saved workflow or a local YAML file
```
pw workflows run [flags]
```
### Examples
```
# Run a saved workflow by name
pw workflows run my-workflow
# Run a marketplace workflow by slug
pw workflows run marketplace/my-marketplace-item
# Run a workflow from a local YAML file
pw workflows run ./my-workflow.yaml
# Run with input parameters
pw workflows run -i '{"param1": "value1"}' my-workflow
# Run with inputs from a JSON file
pw workflows run -i inputs.json my-workflow
# Run with saved inputs
pw workflows run --saved-inputs my-inputs my-workflow
# Run with saved inputs, overriding individual values from --inputs
pw workflows run --saved-inputs my-inputs -i '{"param1": "value1"}' my-workflow
# Validate workflow without executing (dry run)
pw workflows run --dry-run my-workflow
# Run with a custom display name
pw workflows run --name "Test run with new params" my-workflow
# Output as JSON
pw workflows run -o json my-workflow
```
### Options
```
--dry-run Validate only, don't execute
-h, --help help for run
-i, --inputs string JSON string or file path with input values
--name string Custom display name for the run
-o, --output string Output format (interactive, json, text) (default "interactive")
--saved-inputs string Name of saved inputs on the workflow to load input values from (overridden by --inputs)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows](/docs/cli/pw/workflows) - Manage workflows
# pw workflows runs
> Source: https://parallelworks.com/docs/cli/pw/workflows/runs
## pw workflows runs
Manage workflow runs
```
pw workflows runs [flags]
```
### Options
```
-h, --help help for runs
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows](/docs/cli/pw/workflows) - Manage workflows
* [pw workflows runs cancel](/docs/cli/pw/workflows/runs/cancel) - Cancel a running workflow run
* [pw workflows runs clean](/docs/cli/pw/workflows/runs/clean) - Delete workflow runs based on filters
* [pw workflows runs errors](/docs/cli/pw/workflows/runs/errors) - Show errors from a workflow run
* [pw workflows runs list](/docs/cli/pw/workflows/runs/list) - List workflow runs
* [pw workflows runs logs](/docs/cli/pw/workflows/runs/logs) - Fetch workflow run logs
* [pw workflows runs view](/docs/cli/pw/workflows/runs/view) - View a workflow run
# pw workflows runs cancel
> Source: https://parallelworks.com/docs/cli/pw/workflows/runs/cancel
## pw workflows runs cancel
Cancel a running workflow run
```
pw workflows runs cancel [flags]
```
### Examples
```
# Cancel a run by slug
pw workflows runs cancel swift-falcon-17
```
### Options
```
-h, --help help for cancel
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows runs](/docs/cli/pw/workflows/runs) - Manage workflow runs
# pw workflows runs clean
> Source: https://parallelworks.com/docs/cli/pw/workflows/runs/clean
## pw workflows runs clean
Delete workflow runs based on filters
```
pw workflows runs clean [flags]
```
### Examples
```
# Delete runs older than 7 days
pw workflows runs clean --older-than-days 7
# Delete all completed runs
pw workflows runs clean --status completed
# Delete specific runs by slug
pw workflows runs clean --slugs swift-falcon-17,quiet-river-83
# Delete completed runs older than 30 days
pw workflows runs clean --older-than-days 30 --status completed
```
### Options
```
-h, --help help for clean
--older-than-days int Delete runs older than N days
--slugs string Comma-separated list of run slugs to delete
--status string Delete runs with status (completed, error, canceled)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows runs](/docs/cli/pw/workflows/runs) - Manage workflow runs
# pw workflows runs errors
> Source: https://parallelworks.com/docs/cli/pw/workflows/runs/errors
## pw workflows runs errors
Show errors from a workflow run
### Synopsis
Extract and display failed jobs and steps from a workflow run with log tails.
```
pw workflows runs errors [flags]
```
### Examples
```
# Show errors as JSON (default)
pw workflows runs errors swift-falcon-17
# Show errors as text
pw workflows runs errors -o text swift-falcon-17
# Show last 100 lines of logs per failed step
pw workflows runs errors --tail 100 swift-falcon-17
```
### Options
```
-h, --help help for errors
-o, --output string Output format (json or text) (default "json")
--tail int Lines of log tail per failed step (default 50)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows runs](/docs/cli/pw/workflows/runs) - Manage workflow runs
# pw workflows runs list
> Source: https://parallelworks.com/docs/cli/pw/workflows/runs/list
## pw workflows runs list
List workflow runs
```
pw workflows runs list [flags]
```
### Examples
```
# List all workflow runs
pw workflows runs list
# List runs with a specific status
pw workflows runs list --status completed
# List runs for a specific workflow
pw workflows runs list --workflow my-workflow
# Search runs by name or slug
pw workflows runs list --search "my run"
# Output as JSON
pw workflows runs list -o json
```
### Options
```
-h, --help help for list
--limit int Maximum number of runs to return (default 50)
--offset int Number of runs to skip
-o, --output string Output format (json, table)
--search string Search by name or slug
--status string Filter by status (running, completed, error, canceled)
--workflow string Filter by workflow name
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows runs](/docs/cli/pw/workflows/runs) - Manage workflow runs
# pw workflows runs logs
> Source: https://parallelworks.com/docs/cli/pw/workflows/runs/logs
## pw workflows runs logs
Fetch workflow run logs
### Synopsis
Fetch step logs from a workflow run. By default shows all steps; use filters to narrow output.
```
pw workflows runs logs [flags]
```
### Examples
```
# Show all logs for a run
pw workflows runs logs swift-falcon-17
# Show only failed step logs
pw workflows runs logs --failed swift-falcon-17
# Show logs for a specific job and step
pw workflows runs logs --job build --step run-tests swift-falcon-17
# Show last 50 lines per step
pw workflows runs logs --tail 50 swift-falcon-17
# Follow logs until run completes
pw workflows runs logs -f swift-falcon-17
# Output as JSON
pw workflows runs logs -o json swift-falcon-17
# Show the run-level executor log (useful when a step fails before producing its own log)
pw workflows runs logs --run-level swift-falcon-17
```
### Options
```
--failed Only show logs from failed/errored steps
-f, --follow Poll and stream new lines until run completes
-h, --help help for logs
--job string Filter to a specific job name
-o, --output string Output format (json)
--run-level Fetch the run-level executor log (logs.out) instead of per-step logs
--step string Filter to a specific step by name or index number (requires --job)
--tail int Last N lines per step (0 = all)
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows runs](/docs/cli/pw/workflows/runs) - Manage workflow runs
# pw workflows runs view
> Source: https://parallelworks.com/docs/cli/pw/workflows/runs/view
## pw workflows runs view
View a workflow run
```
pw workflows runs view [flags]
```
### Examples
```
# View a run interactively
pw workflows runs view swift-falcon-17
# View a run by ID
pw workflows runs view 507f1f77bcf86cd799439011
# Print run details as text
pw workflows runs view -o text swift-falcon-17
# Output as JSON
pw workflows runs view -o json swift-falcon-17
```
### Options
```
-h, --help help for view
-o, --output string Output format (interactive, text, json) (default "interactive")
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows runs](/docs/cli/pw/workflows/runs) - Manage workflow runs
# pw workflows update
> Source: https://parallelworks.com/docs/cli/pw/workflows/update
## pw workflows update
Update a workflow
```
pw workflows update [flags]
```
### Examples
```
# Update workflow YAML from a file
pw workflows update --yaml workflow.yaml my-workflow
# Update workflow display name
pw workflows update --display-name "My Workflow" my-workflow
# Update workflow description
pw workflows update --description "Runs batch jobs" my-workflow
# Update multiple fields at once
pw workflows update --yaml workflow.yaml --display-name "New Name" my-workflow
```
### Options
```
--description string New description for the workflow
--display-name string New display name for the workflow
-h, --help help for update
-o, --output string Output format (json)
--yaml string Path to YAML file to replace workflow definition
```
### Options inherited from parent commands
```
--context string The context to use. Overrides PW_CONTEXT environment variable and current context from config.
--platform-host string The Parallel Works ACTIVATE platform host to use. Will override any other platform host settings.
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [pw workflows](/docs/cli/pw/workflows) - Manage workflows
# Compute
> Source: https://parallelworks.com/docs/compute
# Compute
ACTIVATE can provision compute in a cloud account or connect infrastructure that your organization already operates. Choose a resource type based on who owns the infrastructure and how much of it you want ACTIVATE to manage.
## Choose a Compute Resource
| Resource type | Best when | What ACTIVATE manages | Start here |
|---|---|---|---|
| **Provisioned cloud cluster** | You want on-demand compute in a connected cloud account | Provisions the cluster from an ACTIVATE configuration and lets you start, stop, and reconfigure it | [Create a cloud cluster](/docs/compute/creating-clusters) |
| **Managed cluster** | Your organization operates a Linux HPC cluster and wants a shared ACTIVATE integration | Monitors registered nodes, can synchronize access, and supports connections through outbound agent tunnels; it does not provision the hardware | [Set up a managed cluster](/docs/compute/managed-clusters) |
| **Existing cluster** | You need a connection from your ACTIVATE account to an HPC cluster whose administrators already manage identities and access | Stores the connection definition and uses your existing cluster account and authentication | [Configure an existing cluster](/docs/compute/configuring-existing-clusters) |
| **Specialized integration** | Your infrastructure requires provider-specific identity or connection steps | Depends on the integration | [Connect a CoreWeave Slurm cluster](/docs/compute/connecting-coreweave-slurm) |
### Provisioned Cloud or Connected Infrastructure?
Choose a **provisioned cloud cluster** when ACTIVATE should create the compute infrastructure for you. A cloud account and its supporting network, storage, and permissions must already be available to ACTIVATE.
Choose a **managed cluster** when an organization administrator wants to expose one shared, organization-owned cluster to users through centralized permissions, monitoring, and optional access synchronization. An administrator installs the ACTIVATE agent on the nodes that ACTIVATE will manage.
Choose an **existing cluster** when each user only needs an SSH connection to infrastructure managed outside ACTIVATE. Users connect with an account and authentication method that already exist on that cluster.
Use a **specialized integration** when the infrastructure has additional provider-specific requirements. For example, CoreWeave Slurm uses an existing-cluster connection plus separate identity synchronization. If you want to run Kubernetes workloads instead of connecting to an HPC scheduler, start with [Kubernetes](/docs/kubernetes).
## Set Up and Use Your Resource
The setup journey depends on the resource type:
1. **Confirm ownership and access.** For cloud clusters, confirm that ACTIVATE has access to the cloud account. For connected infrastructure, coordinate with its Linux, scheduler, identity, and network administrators.
2. **Create or connect the resource.** Follow the setup guide linked in the table above.
3. **Validate access.** Confirm that the resource appears in **Compute > Clusters** and test a connection with a pilot user before expanding access.
4. **Run work.** Use the resource to [run workflows](/docs/run/workflows/running-workflows), open [interactive sessions](/docs/run/sessions), or [submit Slurm jobs](/docs/compute/submitting-jobs), according to the capabilities of that resource.
5. **Monitor and operate it.** Review resource and job activity under **Compute** and [Monitoring](/docs/monitoring). Cloud infrastructure remains subject to its provider's usage charges while it is running.
:::tip Not sure which connected-cluster option to choose?
Use a managed cluster when you need a shared organization-level integration, node monitoring, agent tunnels, or ACTIVATE-managed Linux access. Use an existing cluster when you only need an individual connection profile.
:::
# Configuring Cloud Clusters
> Source: https://parallelworks.com/docs/compute/configuring-cloud-clusters
# Configuring Cloud Clusters
This page explains the parameters of a cluster’s configuration page.
Most ACTIVATE users will work exclusively with elastic clusters. These clusters are made up of a controller node and compute nodes, with the controller delegating tasks to the compute nodes.
Clusters have several adjustable parameters for both controller and compute nodes, such as compute instance types and node count. Additionally, compute nodes are grouped together in partitions, which have their own settings. For more information, see [**Partition Settings**](/docs/compute/configuring-cloud-clusters#partition-settings) below.
ACTIVATE also supports an optional parallel filesystem, Lustre. For more information on setting up Lustre for your account, see [**Configuring Storage**](/docs/storage/configuring-storage).
## Accessing Configuration Settings
You can access a resource’s configuration settings from the **Clusters** page. Click the name of the resource you want to configure.
Alternatively, if you have the **Compute** module on your **Dashboard**, click the gear icon for the resource you want to configure.
Once you've navigated to your cluster, click **Edit**.
## About Saving
When you change settings for a cluster, you must click **Save Changes**.
## About Live Updatable Settings
Some settings can be updated while a cluster is running. These settings are marked with a icon on this page.
When you change a live updatable setting, click **Save Changes**. A dialog box will appear with the message _Changing configuration while cluster is running will make it unavailable until the changes are complete. Are you sure you want to save?_
Click **Save**. Once your cluster updates, a notification will appear with the message _Cluster [name] configuration updated successfully_.
## General Settings
Clusters will typically have these settings in the **Definition** tab of the configuration page. Settings with an asterisk \* are required.
#### Name
Use this field to name the cluster. The name you choose must be unique across your account. For example, you cannot have both a cluster and a storage resource named "demo".
#### Display Name
Use this field to give the cluster a display name, which will appear at the top of the cluster's page, on the **Clusters** page, and on the Dashboard in the **Compute** module. If you leave this field blank, the value for the cluster's **Name** will be displayed instead.
#### Description
Use this field to give the cluster a description of 100 characters or fewer.
#### Tags
Use this field to add tags to the cluster. Tags appear on the **Clusters** page. They are useful for information at a glance (such as "user guide" tags on the clusters we use for our documentation).
#### Network
Use this dropdown menu to select the network that your organization uses for a specific cloud service provider. If you're not sure which one to select, please contact your organization's administrator. For more information about networks, see [**Networks**](/docs/organization-admin/cloud/cloud-accounts/networks).
#### Group
Use this dropdown menu to select the group name that your organization uses to allocate costs. This menu is especially important if your organization is running multiple groups simultaneously.
If you’re not sure which group to select, you can contact us or your organization’s ACTIVATE administrator.
## Controller Settings
These settings define the configuration for the controller node, such as region, instance type, and OS image. Some settings will differ depending on which type of resource you’re using. For more information, see [**CSP-Specific Settings**](/docs/compute/configuring-cloud-clusters/#csp-specific-settings) below.
#### Region
Use this dropdown menu to select the region that your cluster will deploy computing resources into.
A region represents a geographic area.
#### Zone
Use this dropdown menu to select the zone to use for the controller.
A zone refers to an isolated location inside a region.
#### Root Size (GiB)
Use this field to specify the size of the root disk in gibibytes (GiB).
#### Instance Type
Use this dropdown menu to select the instance type of the controller. The instance type determines the CPUs and amount of memory available on the machine. Certain instance types may also have specialty hardware, such as GPUs or low-latency networking options.
To see a list of available instance types and their cost per hour, click **See all sizes**. From the instance type list, you can click an option to select it.
For more information about instance types and what their names mean, please see [**Choosing Instance Types**](/docs/compute/instance-types).
#### Image
Use this dropdown menu to select the operating system (OS) image for the cluster's controller node.
If you're not sure which image to pick, we recommend using the latest version because this will ensure you have the most up-to-date software on your cluster; the latest image version includes OS updates and software required to connect to the ACTIVATE control plane.
You can also use this dropdown menu to select custom cloud snapshots.
#### IP Address
Use this dropdown menu to choose the IP address that will be assigned to the cluster. You can choose an automatically assigned IP address or an IP address that you've created.
For more information, please see [**Managing IP Addresses**](/docs/compute/managing-ip-addresses).
## CSP-Specific Settings
Each cloud service provider (CSP) builds and configures their resources differently. Clusters on ACTIVATE have settings that correspond to each CSP’s model of cloud services. The CSP-specific parameters are outlined below.
Please note that these CSP-specific settings will also appear as options inside the partition settings on clusters.
### Google
#### Tier 1
Use this toggle button to enable Tier 1, which increases maximum egress bandwidth (upload speed) to 50–100 Gps, depending on the size of the instance. If Tier 1 is off, the egress bandwidth will range from 10–32 Gbps.
For more information, see the [Google documentation on Tier 1](https://cloud.google.com/compute/docs/networking/configure-vm-with-high-bandwidth-configuration#limitations).
## Partition Settings {#partition-settings}
You can create partitions in clusters to send your work to homogenously configured sets of worker nodes.
If you click **+ Add Partition**, a list of new settings will appear. Typically, a partition will have the following configuration options. Some settings will differ depending on which type of resource you’re using. For more information, see [**CSP-Specific Settings**](/docs/compute/configuring-cloud-clusters/#csp-specific-settings) below.
#### Name
Use this field to name your partition. You must use a unique name for each partition you create.
#### Instance Type
Use this dropdown menu to select the configuration of the partition. These options work in the same way that the controller instance types do.
#### GPU
_Available on Google N1 instance types._
Use this dropdown menu to attach a GPU to the partition's instances. Only GPUs that are available in the selected zone(s) are shown.
Currently, only the **NVIDIA T4** can be selected. Other GPU types are listed but disabled because the recent NVIDIA drivers baked into most of our node images support only newer GPU architectures (NVIDIA Turing and later); older GPUs such as the V100 (Volta) and P100/P4 (Pascal) are no longer supported by those drivers.
#### GPU Count Per Node
Use this field to set how many GPUs to attach to each node in the partition. It appears alongside the **GPU** dropdown on N1 instances.
#### Max Nodes
Use this field to enter the max number of nodes in a partition.
#### Elastic Image
Use this dropdown menu to select the operating system image for the partition. We recommend using the latest version.
#### MultiZone
Enable this toggle to provision nodes in multiple zones. If there is not enough capacity in one zone, we will try to provision nodes in a different zone. This can be helpful for obtaining instances that are in high demand.
The exact behavior depends on the cloud provider:
- **AWS**: All nodes in a single request are placed in the same zone. If a zone cannot fit every node in the batch, we move the entire batch to the next zone you selected and try again. When adding nodes to a running cluster, we try the zone that already holds the most of the cluster's nodes first; if the cluster has no nodes yet, we try the controller's zone first when it is one of your selected zones.
- **Google**: A single request is submitted at the region level, along with your list of allowed zones. Google Cloud then chooses zones from that list based on available capacity, so the request can spread or fall back across zones automatically.
- **Azure**: Azure clusters do not use the **MultiZone** toggle. Selecting **Automatic** from the **Zone** dropdown instead lets Azure distribute the partition's compute nodes across the region's availability zones for you.
:::warning Warning
If nodes are provisioned in multiple zones, there may be costs associated with data transfer between zones. For more information, see the [**AWS documentation on data transfer costs**](https://aws.amazon.com/ec2/pricing/on-demand/#Data_Transfer) or the [**Google documentation on data transfer costs**](https://cloud.google.com/compute/network-pricing#egress_only_ip_addresses).
:::
#### Zone(s)
Use this dropdown menu to select which zone(s) nodes will be provisioned in within your selected region. If **MultiZone** is enabled, you can select multiple zones.
#### Default
Use this toggle button to specify whether a partition is the default location for running jobs. For more information on running jobs on specific partitions, see [**Submitting Jobs**](/docs/compute/submitting-jobs).
:::info Default Partition
This feature is important if you create multiple partitions. If you only create one partition, it will automatically be set to **Default** and cannot be changed, as shown in the screenshot above.
:::
#### Use Placement Group
_Currently available only on AWS and Google clusters._
Use this toggle button to enable the partition's instances to be launched as a placement group.
Typically, partition instances are launched throughout a zone. This strategy minimizes the chances of disprupting users' work: if one of the instances fails, especially from an outage or damage, the other instances are likely to remain unaffected.
With a placement group, the instances are instead launched close together. This strategy can improve network performance and is best suited for jobs that are small, short, or will not be affected by interruptions.
For AWS clusters, this setting is enabled by default.
#### Provisioning Mode
_Available on AWS, Azure, and Google clusters._
Use this dropdown menu to choose how the partition's instances are provisioned. It defaults to **Standard**.
- **Standard**: On-demand instances that run for any duration you set. Ideal for most workloads.
- **Preemptible**: Lower cost, but can be reclaimed by the cloud at any time. Ideal for fault-tolerant workloads. Because another user can take over the resource at any time, use preemptible instances at your own risk.
- **Flex-start** _(Google clusters only)_: Queued provisioning for scarce GPU capacity. May take hours or days to be fulfilled, then runs for up to 7 days. Available only on GPU or H4D instance types. Built on Google's [Dynamic Workload Scheduler](https://cloud.google.com/compute/docs/instances/about-flex-start-vms).
:::info Flex-start and Dynamic Workload Scheduler
Flex-start is available only on Google clusters and is built on Google Cloud's [Dynamic Workload Scheduler (Flex-start VMs)](https://cloud.google.com/compute/docs/instances/about-flex-start-vms). Instead of failing immediately when in-demand GPU capacity is unavailable, a flex-start request is _queued_ and fulfilled once capacity frees up — which can take minutes, hours, or longer. Once capacity is granted, the node runs for up to 7 days. Flex-start is best suited to GPU workloads that can tolerate a delayed, non-deterministic start in exchange for better access to scarce hardware.
:::
#### Flex-start Wait Time (seconds)
_Appears when **Provisioning Mode** is set to **Flex-start** (Google clusters)._
Use this field to set how long to wait for flex-start capacity before giving up. This is required for flex-start and accepts a value from 30 seconds to 7 days (604,800 seconds). It defaults to `300`.
#### Max Run Duration (seconds)
Use this field to set the maximum time a node runs before it is deleted automatically.
For **Flex-start** partitions this is required and must be between 600 seconds and 7 days. For other provisioning modes it is optional — leave it empty for no limit.
#### Capacity Reservation\*
_Before you can use a capacity reservation on ACTIVATE, it must first be configured by an administrator in your organization. After this initial step, your administrator can distribute the values for **Reservation ID** and, if necessary, **Placement Group**._
Use this toggle button to enable on-demand capacity reservations, which reserve a set amount of compute capacity.
When **Capacity Reservation** is enabled, a **Reservation ID** dropdown menu will appear. For AWS, you will also enter the **Placement Group**.
## Attached Filesystems Settings
Use this section to attach any of your configured storage resources. For more information, please see [**Attaching Storage**](/docs/storage/attaching-storage).
## Advanced Settings
### Admin Settings
#### Debug Mode
Use this toggle button to disable clean-up for provisioning failures. The cluster owner will also have root access to the nodes for debugging purposes (`ssh root@`).
### Script Settings
Optionally, you can set scripts to execute when you start a cluster.
#### User Bootstrap
Use this text box to set a script that executes once a controller node has started. For example, you can set files to automatically move into a specific folder.
#### Bootstrap Controller
Use this toggle button to specify whether your bootstrap script will run on the controller node.
#### Bootstrap Compute Nodes
Use this toggle button to specify whether your bootstrap script will run on compute nodes.
#### Health Check
Use this text box to set a script that runs a health check on a controller node. When the script is done running, you’ll see any error codes in red or an exit code of `0` in green if there are no errors.
For more information, see **Health Checks** (coming soon).
### Scheduler Settings
ACTIVATE uses [Slurm](https://slurm.schedmd.com/documentation.html) to manage jobs on controller and compute nodes. The settings below determine how Slurm behaves for your cluster's nodes.
Please note that numerical values you enter in these fields are measured in seconds.
#### Suspend Time
Use this field to set how long Slurm will wait before shutting down idle nodes. This field is set to `300` by default.
#### Resume Timeout
Use this field to set the maximum amount of time Slurm will try to start nodes. If the nodes don’t start by the end of the set time, Slurm will end the initialization attempt. This field is set to `1200` by default.
#### Suspend Timeout
Use this field to set how long Slurm will wait to make nodes available again after shutting them down. This field is set to `300` by default.
#### Return To Service
Use this dropdown menu to select when down nodes are returned to service.
The `Non Responsive` option means that down nodes will become available only if they were set to down because they were non-responsive.
The `Any Reason` option means that down nodes will become available if they were set to down for any reason, including low memory, an unexpected reboot, or being non-responsive.
This field is set to `Non Responsive` by default.
### User Workspace Mount Points
You can specify multiple mount points for your cluster, which makes it easier to view, upload, and edit cluster files in the ACTIVATE **Editor** and terminal.
#### Cluster Path
Use this field to enter the path that will be mounted from your cluster to your user workspace. You can use the following substitutions:
- `__HOME__` is the user home directory on your cluster.
- `__USER__` will be replaced by your cluster's remote username; this username may be the same as your ACTIVATE username in some cases.
#### Workspace Path
Use this field to enter the path to mount the cluster inside your user workspace. You can use the following substitutions:
- `__HOME__` is the user workspace home directory.
- `__USER__` will be replaced by your ACTIVATE username.
- `__CLUSTER__` will be replaced by your cluster's name.
### Alerts
#### Runtime Alert
Use this toggle button to enable runtime alerts. When enabled, you'll receive an automated email from noreply@parallelworks.com at a set hourly interval, reminding you that your cluster is still running:
```md
Dear {username},
This is an automated message to inform you that your cluster {cluster_name} has been running for {time} hours. Please take note of the following details:
Cluster name: {cluster_name}
Cluster start time: {start_date}
Total run time: {total_time}
Next alert time: {next_alert}
This alert can be turned off in the resource's properties page.
Sincerely,
Parallel Works
```
#### Session Cost Limit
Use this toggle button to enable a session cost limit. When enabled, your cluster will be destroyed and you'll receive an automated email from noreply@parallelworks.com:
```md
Dear {username},
This is an automated message to inform you that the current session for your cluster {cluster_name} has exceeded the cost limit. Please take note of the following details:
Resource name: {cluster_name}
Resource start time: {start_date}
Total run time: {total_time}
Current session cost: {current_cost}
Session cost limit: {cost_limit}
Your cluster will be terminated. Data saved on this resource is not recoverable. This automated action can be turned off in the resource's properties page under Session Cost Limit.
Sincerely,
Parallel Works
```
## Load From Marketplace
You can load pre-configured settings from existing resources in the Marketplace.
First, [add an item](/docs/marketplace#favoriting-workflows) from the Marketplace.
Next, create a new resource or navigate to an existing resource's settings. Click **Edit**, then **Load From Marketplace**.
After you click **Load From Marketplace**, a dialog box will appear with more information: *This will change the cluster settings to a configuration from the Marketplace. Restoring will overwrite all changes you have made to these sections. Filesystems are configured separately. For more information, see [the documentation](/docs/storage).*
Choose your resource from the dropdown menu, then click **Restore**.
# Configuring Existing Clusters
> Source: https://parallelworks.com/docs/compute/configuring-existing-clusters
# Configuring Existing Clusters
ACTIVATE allows users to access the capabilities of an existing HPC cluster remotely.
:::info Looking for an organization-managed integration?
Use a [managed cluster](/docs/compute/managed-clusters) when you want an organization-owned resource with explicitly registered nodes, centralized access management, resource monitoring, and sessions through a selected node. Continue with this guide when an individual user should connect through HPC Connect with an account and authentication method that the cluster already manages.
:::
## Creating a Cluster Definition
Navigate to the **Clusters** page under the **Compute** tab.
Click the **+ Add Resource** button
Select **Existing Cluster**.
You must enter a **Resource Name**. The **Display Name**, **Short description**, and **Tags** are all optional.
Click the **Add Resource** button.
On the next page, click the **Definition** tab.
If the existing cluster you wish to connect to utilizes a jump host, select **Yes** for the **Jump Node** option. Enter the proper **Jump Node User** and **Jump Node Host** information to continue.
In the **Cluster Configuration** section, enter the **Username** and **Cluster Login Node**. Typically, the **Cluster Login Node** refers to the IP address of the cluster you wish to access. Your organization should have provided this information to you.
Click **Save Changes**.
## Connecting to the Cluster
After configuring the cluster, navigate to the **Sessions** tab and click the power button.
A dialog box will appear that will show HPC Connect authenticating your connection.
If your organization uses multi-factor authentication, you will be prompted to enter a token. This may be an RSA token, YubiKey, or other type of token that’s specific to your organization.
This prompt will also appear if you use a passphrase protected key instead of the default workspace key.
If no token is required, you will be connected to the cluster immediately.
Once you're logged in to the cluster, you can run workflows as well as browse, edit, and upload files using the [**Editor**](/docs/your-workspace/editor).
## Disconnecting
After you've finished utilizing the cluster, click the power button in the **Sessions** tab. A dialog box will appear. Click **Turn Off**.
A notification will appear in the bottom right corner of your screen with the message _Stopping [cluster name]_.
## Configuring Settings
Typically when you create an existing cluster, you’ll be connecting to an on-premises cluster associated with your organization. However, the instructions here for existing clusters can be used with any pre-created Slurm cluster. The settings that are specific to this type of cluster are outlined below. If you’re unsure what to choose for these options, contact your organization’s ACTIVATE administrator.
### General Settings
#### Resource Account
Use this dropdown menu to select how ACTIVATE will connect to the existing cluster.
The `User Workspace (~/ssh/pw_id_rsa)` options means that ACTIVATE will try to SSH to the cluster by using only your account’s SSH key, which is stored at `~/.ssh/pw_id_rsa`. For more information about your SSH key, see [our documentation](/docs/compute/logging-in-controller#why-dont-i-have-to-use-an-ssh-key-from-within-the-platform).
#### Jump Node
Use this toggle button if you’re connecting to a cluster that has a jump node enabled. A jump node—also called a host node, bastion node, or login node—is a high-security server that allows a user to access a private machine or network.
If you enable this feature, two new fields will appear for **Jump Node User** and **Jump Node Host**. Your organization will have these credentials if you need them.
### Cluster Configuration Settings
#### Username
Use this field to enter the username assigned to you for this cluster.
:::info Username substitution
On existing clusters, you can enter `__USER__` into any box and ACTIVATE will automatically substitute your username for that field. For example, if your username is `jdoe`, ACTIVATE will automatically substitute `__USER__` for `jdoe` in the **Working Directory** field.
:::
#### Cluster Login Node
Use this field to enter the IP address or host name of the cluster.
#### Scheduler Type
Use this dropdown menu to select the type of job scheduler the cluster uses. Currently, the **Existing Cluster** resource type supports Slurm and PBS.
# Connecting a CoreWeave Slurm Cluster
> Source: https://parallelworks.com/docs/compute/connecting-coreweave-slurm
# Connecting a CoreWeave Slurm Cluster
This guide connects a [CoreWeave](https://www.coreweave.com/) Slurm cluster (SUNK - Slurm on Kubernetes) to ACTIVATE so your users can submit batch jobs, open desktop sessions, and run workflows on it.
There are two sides to it:
1. **Identity** - point the cluster's identity cache (`nsscache`) at ACTIVATE's SCIM API and add an SSH authorized-keys command, so ACTIVATE users, groups, and SSH keys resolve as real Linux accounts on the cluster.
2. **Connection** - register the cluster in ACTIVATE as an [existing cluster](/docs/compute/configuring-existing-clusters).
Each identity step below can be applied two ways - pick one and stay consistent:
- **Helm values (GitOps)** - set everything in the values file your SUNK `slurm` chart deployment consumes. This is the right choice when the deployment is managed through ArgoCD (the usual setup for CoreWeave-managed clusters). Depending on the Application's sync policy, hand-edited chart-managed resources are reverted immediately (self-heal), reverted on the next sync (auto-sync), or left in place but flagged as out-of-sync drift. Changes made through the values file survive in every case.
- **kubectl (manual)** - edit the ConfigMaps directly. Fine for a quick proof of concept, or on clusters where automatic sync is disabled.
:::info Connecting CoreWeave's Kubernetes API instead?
If you want to manage the cluster's Kubernetes workloads through ACTIVATE rather than submit Slurm jobs, see [Connecting CoreWeave (Kubernetes)](/docs/kubernetes/connecting-clusters/coreweave).
:::
## Prerequisites
- **Organization admin permissions** in ACTIVATE.
- **SCIM provisioning enabled** for your organization, plus a **bearer token**. Follow [SCIM Provisioning](/docs/organization-admin/scim) first and keep the token and endpoint URL handy.
- **`kubectl` access** to the cluster's `tenant-slurm` namespace (via the kubeconfig from CoreWeave).
- For the Helm values method, **write access to the GitOps repository** whose values file the `slurm` ArgoCD Application consumes.
- POSIX UIDs/GIDs and SSH public keys configured on your ACTIVATE users and groups - these are what get synchronized onto the cluster.
## Point nsscache at ACTIVATE's SCIM API
CoreWeave's SUNK clusters resolve Linux identity through `nsscache`, which periodically syncs `passwd`, `group`, `shadow`, and `sshkey` maps from a source. We configure that source to be ACTIVATE's SCIM API, reading POSIX identity from the [CoreWeave extension attributes](/docs/organization-admin/scim#coreweave-extension-attributes).
**Helm values (GitOps)**
Add the following to the values file consumed by your `slurm` chart deployment. The two values you must set for your organization are **`scim_base_url`** (your SCIM endpoint) and **`scim_users_parameters`** (which requests the CoreWeave user extension). The chart's defaults fill in the rest of `nsscache.conf` (cache locations, `[passwd]`, `[shadow]`, and `[sshkey]` paths):
```yaml
nsscache:
enabled: true
existingSecret: nsscache-scim-secret
nsscacheConfig:
default:
source: scim
scim_base_url: https:///api/organizations//scim/v2
scim_users_endpoint: Users
scim_users_parameters: attributes=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveUser
scim_groups_endpoint: Groups
scim_groups_parameters: excludeInactiveUsers=true
passwd:
scim_override_home_directory: /mnt/home/%%u
group:
scim_path_gid: urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveGroup/sunkPosixGroupId
scim_path_groupname: urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveGroup/sunkPosixGroupName
```
No restarts are needed after this syncs: the nsscache update CronJob runs every minute and mounts the rendered config fresh on each run.
**kubectl (manual)**
Edit the nsscache ConfigMap in the `tenant-slurm` namespace. Its name is prefixed with the Helm release name, typically `slurm`:
```bash
kubectl edit cm/slurm-nsscache-conf -n tenant-slurm
```
Update it to match the following. The two values you must set for your organization are **`scim_base_url`** (your SCIM endpoint) and **`scim_users_parameters`** (which requests the CoreWeave user extension):
```yaml
apiVersion: v1
data:
nsscache.conf: |
[DEFAULT]
cache=files
files_cache_filename_suffix=cache
files_dir=/etc/nsscache
maps=passwd,shadow,group,sshkey
scim_base_url=https:///api/organizations//scim/v2
scim_groups_endpoint=Groups
scim_groups_parameters=excludeInactiveUsers=true
scim_users_endpoint=Users
scim_users_parameters=attributes=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveUser
source=scim
timestamp_dir=/var/lib/nsscache
[group]
scim_path_gid=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveGroup/sunkPosixGroupId
scim_path_groupname=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveGroup/sunkPosixGroupName
scim_path_username=members/sunkPosixUsername
[passwd]
scim_default_shell=/bin/bash
scim_override_home_directory=/mnt/home/%%u
scim_path_gid=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveUser/sunkPosixGroupId
scim_path_home_directory=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveUser/sunkPreferredHomeDirectory
scim_path_login_shell=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveUser/sunkLoginShell
scim_path_uid=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveUser/sunkPosixUserId
scim_path_username=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveUser/sunkPosixUsername
[shadow]
scim_path_username=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveUser/sunkPosixUsername
[sshkey]
scim_path_ssh_keys=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveUser/sunkSshKeys
scim_path_username=urn:coreweave:params:scim:schemas:extension:coreweave:2.0:CoreWeaveUser/sunkPosixUsername
nsswitch.conf: |
group: files cache
passwd: files cache
```
:::warning
On an ArgoCD-managed deployment, this edit is reverted immediately if self-heal is enabled, or on the next sync with auto-sync; even with automatic sync disabled, the Application reports it as out-of-sync drift. Use the Helm values method instead.
:::
What the key settings do:
- **`scim_base_url`** - your organization's SCIM endpoint, shown on the [SCIM Provisioning](/docs/organization-admin/scim) page (`https:///api/organizations//scim/v2`).
- **`scim_users_parameters=attributes=...CoreWeaveUser`** - requests the CoreWeave user extension. ACTIVATE omits that block by default, so without this parameter the POSIX UID/GID, shell, home directory, and SSH keys would be missing.
- **`scim_groups_parameters=excludeInactiveUsers=true`** - drops disabled ACTIVATE accounts from group membership, so deactivated users stop resolving on the cluster.
- **`[group]` paths with the `...CoreWeaveGroup` URN prefix** - ACTIVATE nests `sunkPosixGroupId` and `sunkPosixGroupName` under the CoreWeave group extension in each Group resource. Without the URN prefix, nsscache looks for them at the top level, finds no GID, and skips every group (`Group missing GID, skipping` in the update job logs). `members/sunkPosixUsername` stays unprefixed - member entries carry that field at the top level.
- **`scim_override_home_directory=/mnt/home/%%u`** - forces home directories under `/mnt/home`. This overrides the `sunkPreferredHomeDirectory` value from SCIM; set it to wherever home directories are mounted on your cluster.
### Provide the bearer token
The SCIM API requires a bearer token on every request. On a SUNK cluster, nsscache reads it from the `nsscache-scim-secret` Secret in the `tenant-slurm` namespace - not from the configuration above (in the Helm values, `nsscache.existingSecret` names it). This Secret is provisioned with the cluster; update it with the token you minted in [SCIM Provisioning](/docs/organization-admin/scim#bearer-tokens):
```bash
kubectl edit secret nsscache-scim-secret -n tenant-slurm
```
Secret values are base64-encoded, so encode the token before pasting it into the Secret's data field:
```bash
printf '%s' '' | base64
```
## Configure the authorized keys command
So that `sshd` can authorize logins using each user's ACTIVATE SSH keys, install an `AuthorizedKeysCommand` that fetches them through the `pw` CLI.
**Helm values (GitOps)**
The SUNK chart embeds its default authorized-keys script directly from a chart file, with no values hook to replace it - so instead of fighting over that ConfigMap, register your own command through two supported values:
- **`login.sshdConfig`** adds an `AuthorizedKeysCommand` line pointing at your script. It renders ahead of the chart's built-in line, and `sshd` honors the first value it sees for a keyword, so yours wins.
- **`login.s6`** runs a oneshot at login-pod startup (as root) that writes the script and pre-installs the `pw` CLI, so key lookups - which run unprivileged - never have to install anything.
Add the following to your values file, **replacing ``** with your platform's hostname throughout. `PasswordAuthentication` and `AllowAgentForwarding` replicate the chart's defaults, which setting `sshdConfig` replaces:
```yaml
login:
sshdConfig: |
PasswordAuthentication no
AllowAgentForwarding yes
AuthorizedKeysCommand /usr/local/share/pw-authorized-keys-command.sh
s6:
pw-authorized-keys-setup:
type: oneshot
timeoutUp: 120000
script: |
#!/usr/bin/env bash
# Writes the AuthorizedKeysCommand script referenced by
# login.sshdConfig and pre-installs the pw CLI as root at pod start,
# so key lookups (which run unprivileged) never need to install it.
set -e
cat > /usr/local/share/pw-authorized-keys-command.sh <<'EOS'
#!/bin/bash
# AuthorizedKeysCommand: fetch the user's SSH public keys via the pw CLI.
set -e
PLATFORM_HOST="${PLATFORM_HOST:-https://}"
PW_INSTALL_DIR="${PW_INSTALL_DIR:-/usr/local/bin}"
PW_BIN="$PW_INSTALL_DIR/pw"
# /tmp is always writable, even by `nobody`. The lock only needs to
# exist during one install attempt, so ephemeral storage is fine.
INSTALL_LOCK="${PW_INSTALL_LOCK:-/tmp/pw-install.lock}"
locate_pw() {
if [ -x "$PW_BIN" ]; then
return
fi
local found
found="$(command -v pw 2>/dev/null || true)"
if [ -n "$found" ] && [ -x "$found" ]; then
PW_BIN="$found"
fi
}
locate_pw
if [ ! -x "$PW_BIN" ]; then
# flock prevents concurrent sshd invocations from racing the install.
(
flock -x 9
if [ ! -x "/usr/local/bin/pw" ] && ! command -v pw >/dev/null 2>&1; then
# Send install output to stderr so it doesn't end up in the
# keys stream sshd reads from stdout.
curl -fsSL https:///cli/install.sh \
| bash -s -- --to "$PW_INSTALL_DIR" 1>&2
fi
) 9>"$INSTALL_LOCK"
locate_pw
fi
if [ ! -x "$PW_BIN" ]; then
echo "pw CLI not found and install failed" >&2
exit 1
fi
# Validate username contains only safe characters.
if [[ ! "$1" =~ ^[a-zA-Z0-9._-]+$ ]]; then
exit 1
fi
exec "$PW_BIN" ssh-public-keys --platform-host "$PLATFORM_HOST" "$1"
EOS
chmod 0755 /usr/local/share/pw-authorized-keys-command.sh
# Best-effort: the authorized-keys script lazily installs pw as a
# fallback, so a transient failure here must not block pod startup.
if ! command -v pw >/dev/null 2>&1 && [ ! -x /usr/local/bin/pw ]; then
curl -fsSL https:///cli/install.sh \
| bash -s -- --to /usr/local/bin \
|| echo "WARN: pw CLI pre-install failed; will retry lazily" >&2
fi
```
The login StatefulSet defaults to the `OnDelete` update strategy, so after this change syncs, delete the login pod to recreate it with the new sshd config and s6 service (find it with `kubectl get pods -n tenant-slurm`):
```bash
kubectl delete pod -n tenant-slurm
```
Confirm it works by execing into the recreated login pod and running the command with a username:
```bash
kubectl exec -it -n tenant-slurm -- \
/usr/local/share/pw-authorized-keys-command.sh
```
**kubectl (manual)**
Replace the content of the chart's authorized-keys ConfigMap. Save the following as `slurm-nsscache-authorized-keys-command.yaml`, **replacing ``** with your platform's hostname throughout:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: slurm-nsscache-authorized-keys-command
namespace: tenant-slurm
data:
# Filename kept as .py for drop-in compatibility with the existing
# AuthorizedKeysCommand path in sshd_config. The shebang determines the
# interpreter, so bash content here is fine.
nsscache-authorized-keys-command.py: |
#!/bin/bash
# AuthorizedKeysCommand: fetch the user's SSH public keys via the pw CLI.
# Installs pw on first invocation; subsequent calls reuse the cached binary.
set -e
PLATFORM_HOST="${PLATFORM_HOST:-https://}"
PW_INSTALL_DIR="${PW_INSTALL_DIR:-/usr/local/bin}"
PW_BIN="$PW_INSTALL_DIR/pw"
# /tmp is always writable, even by `nobody`. The lock only needs to exist
# during one install attempt, so ephemeral storage is fine.
INSTALL_LOCK="${PW_INSTALL_LOCK:-/tmp/pw-install.lock}"
locate_pw() {
if [ -x "$PW_BIN" ]; then
return
fi
local found
found="$(command -v pw 2>/dev/null || true)"
if [ -n "$found" ] && [ -x "$found" ]; then
PW_BIN="$found"
fi
}
locate_pw
if [ ! -x "$PW_BIN" ]; then
# flock prevents concurrent sshd invocations from racing the install.
(
flock -x 9
if [ ! -x "/usr/local/bin/pw" ] && ! command -v pw >/dev/null 2>&1; then
# Send install output to stderr so it doesn't end up in the
# keys stream sshd reads from stdout.
curl -fsSL https:///cli/install.sh \
| bash -s -- --to "$PW_INSTALL_DIR" 1>&2
fi
) 9>"$INSTALL_LOCK"
locate_pw
fi
if [ ! -x "$PW_BIN" ]; then
echo "pw CLI not found and install failed" >&2
exit 1
fi
# Validate username contains only safe characters.
if [[ ! "$1" =~ ^[a-zA-Z0-9._-]+$ ]]; then
exit 1
fi
exec "$PW_BIN" ssh-public-keys --platform-host "$PLATFORM_HOST" "$1"
```
Apply it:
```bash
kubectl apply -f slurm-nsscache-authorized-keys-command.yaml
```
:::warning
This ConfigMap is owned by the SUNK Helm chart, which hardcodes its content - on an ArgoCD-managed deployment, this edit is reverted immediately if self-heal is enabled, or on the next sync with auto-sync; even with automatic sync disabled, the Application reports it as out-of-sync drift. Use the Helm values method instead.
:::
A running login pod won't pick up the new ConfigMap until it restarts. Delete the Slurm login pod so it's recreated with the updated command mounted (find it with `kubectl get pods -n tenant-slurm`):
```bash
kubectl delete pod -n tenant-slurm
```
Confirm it works by execing into the recreated login pod and running the command with a username:
```bash
kubectl exec -it -n tenant-slurm -- \
/usr/local/share/nsscache-authorized-keys-command.py
```
On the first SSH login after the pod comes back, the script installs the `pw` CLI if it isn't already present, then calls `pw ssh-public-keys` to return the user's keys for `sshd` to authorize. When everything is wired up correctly, running the command manually prints that user's authorized SSH public keys - for example, passing `mcquade` returns mcquade's keys.
## Register the cluster in ACTIVATE
With identity resolving on the cluster, connect it like any other on-premises cluster:
1. Follow [Configuring Existing Clusters](/docs/compute/configuring-existing-clusters) to create the cluster definition.
2. Set the **Scheduler Type** to **Slurm**.
3. Enter the **Cluster Login Node** (the cluster's login/jump host) and your **Username**.
You can use the `__USER__` token in any field and ACTIVATE substitutes the logged-in user's username automatically.
## Verify
First, confirm the identity cache is populating. nsscache writes each synced map into a `slurm-nsscache-