CLI Reference

Reference for every px command and its flags.

INFO

This page mirrors px --help. For the version you have installed, px <command> --help is always the source of truth.

px

PX - Parallel made simple: easy mode for multi-core & multi-node.

Usage: px [OPTIONS] COMMAND [ARGS]...

Options

Option	Description
-V, --version	Show version and exit
-h, --help	Show this message and exit

Commands

Command	Description
cloud	Manage cloud provider authentication
cluster	Manage cloud clusters for distributed job execution
doctor	Run diagnostic tests on specified subsystems
job	Manage cluster jobs
login	Authenticate with PX Dash
logout	Remove stored PX Dash credentials
run	Run a command in parallel locally
superx	Manage PX Supervisor (superx) operations

Command Shortcuts

clusters, jobs, logs, status, and submit are top-level shortcuts for cluster ls, job ls, job logs, job status, and job submit.

px cloud

Manage cloud provider authentication.

Usage: px cloud [OPTIONS] COMMAND [ARGS]...

Commands

Command	Description
login	Authenticate with cloud providers

px cloud login

A thin wrapper around native cloud provider CLI authentication tools.

Usage: px cloud login [OPTIONS] [[gcp]]

Examples:

• px cloud login: authenticate with all providers
• px cloud login gcp: authenticate only with GCP

Supported providers:

• gcp: uses gcloud auth login --update-adc (requires the gcloud CLI installed and on PATH)

For advanced authentication options, use the native CLI tools directly (e.g. gcloud auth login --help).

Arguments

Argument	Description
PROVIDER	Cloud provider to authenticate with (default: all)

Options

Option	Description
--no-launch-browser	Skip launching browser for authentication (when supported)
-h, --help	Show this message and exit

px cluster

Manage cloud clusters for distributed job execution.

Usage: px cluster [OPTIONS] COMMAND [ARGS]...

Commands

Command	Description
up	Create and provision a cluster on the cloud
down	Terminate a cluster and all associated cloud resources
ls	List clusters with status, cost, and resource summary
status	Show detailed status for a live cluster
sync	Sync workdir to a cluster
generate-config	Generate a px.yaml.example template in the current directory

px cluster up

Create and provision a cluster on the cloud.

Usage: px cluster up [OPTIONS] CLUSTER_NAME

Arguments

Argument	Description
CLUSTER_NAME	Name of the cluster to create

Options

Option	Description
--spec-file FILE	YAML file with cluster specifications
--dry-run	Preview changes without creating resources
-v, --verbose	Show in-progress sync and mount details
-h, --help	Show this message and exit

px cluster down

Terminate a cluster and all associated cloud resources.

Usage: px cluster down [OPTIONS] CLUSTER_NAME

Arguments

Argument	Description
CLUSTER_NAME	Name of the cluster to terminate

Options

Option	Description
-h, --help	Show this message and exit

px cluster ls

List clusters with status, cost, and resource summary.

Usage: px cluster ls [OPTIONS]

Options

Option	Description
-a, --all	Show all clusters instead of recent ones
-o, --output [console|json]	Output format (default: console)
-h, --help	Show this message and exit

px cluster status

Show detailed status for a live cluster.

Usage: px cluster status [OPTIONS] CLUSTER_NAME

Arguments

Argument	Description
CLUSTER_NAME	Name of the cluster to inspect

Options

Option	Description
-o, --output [console|json]	Output format (default: console)
-h, --help	Show this message and exit

px cluster sync

Sync workdir to a cluster.

Usage: px cluster sync [OPTIONS] CLUSTER_NAME

Arguments

Argument	Description
CLUSTER_NAME	Name of the cluster to sync to

Options

Option	Description
--spec-file FILE	YAML file with cluster specifications
--run-setup	Rerun the setup step after syncing
-h, --help	Show this message and exit

px cluster generate-config

Generate a px.yaml.example template in the current directory.

Usage: px cluster generate-config [OPTIONS]

Options

Option	Description
-h, --help	Show this message and exit

px doctor

Run diagnostic tests on specified subsystems to verify proper configuration.

Usage: px doctor [OPTIONS] [[cloud|cpu|ssh]]

Arguments

Argument	Description
SUBSYSTEM	Subsystem to check: cloud, cpu, or ssh. Omit to run all checks.

Options

Option	Description
-h, --help	Show this message and exit

px job

Manage cluster jobs.

Usage: px job [OPTIONS] COMMAND [ARGS]...

Commands

Command	Description
submit	Submit a job for execution on a cluster
ls	Print a list of cluster's jobs
status	Show detailed status for a job
logs	Stream logs for a job (historical + live)

px job submit

Submit a job for execution on a cluster.

Usage: px job submit [OPTIONS] COMMAND [ARGS]...

Arguments

Argument	Description
COMMAND	The command to run in parallel

Options

Option	Description
-a, --args-file FILE	Read input arguments from a file instead of stdin or command line
-p, --parallelism INTEGER	Number of parallel tasks to run (default: system capacity)
-c, --cluster TEXT	Cluster to submit the job to
-d, --detach	Submit job and return without streaming logs
-h, --help	Show this message and exit

px job ls

Print a list of cluster's jobs.

Usage: px job ls [OPTIONS]

Options

Option	Description
-c, --cluster TEXT	Name of the cluster where jobs are running
-h, --help	Show this message and exit

px job status

Show detailed status for a job.

Usage: px job status [OPTIONS] JOB_ID

Arguments

Argument	Description
JOB_ID	The job ID to inspect

Options

Option	Description
-c, --cluster TEXT	Name of the cluster where the job is running
-o, --output [console|json]	Output format (default: console)
-h, --help	Show this message and exit

px job logs

Stream logs for a job running on a cluster (historical + live). Connects to the supervisor and streams all available logs. Historical logs are sent first, followed by live logs as they're produced.

Usage: px job logs [OPTIONS] JOB_ID

Arguments

Argument	Description
JOB_ID	The job ID to stream logs for

Options

Option	Description
-c, --cluster TEXT	Name of the cluster where the job is running
--stream [all|stdout|stderr]	Stream type to display (default: all)
-h, --help	Show this message and exit

px login

Authenticate with PX Dash. Guides you through obtaining and validating an API token from px.app. The token is stored locally for use by subsequent commands.

Usage: px login [OPTIONS]

Options

Option	Description
--force	Force re-authentication even if already logged in
-h, --help	Show this message and exit

px logout

Remove stored PX Dash credentials, logging you out from PX Dash.

Usage: px logout [OPTIONS]

Options

Option	Description
-h, --help	Show this message and exit

px run

Run a command in parallel locally. For cluster execution, use px job submit.

Usage: px run [OPTIONS] COMMAND [ARGS]...

Arguments

Argument	Description
COMMAND	The command to run in parallel

Options

Option	Description
-a, --args-file FILE	Read input arguments from a file instead of stdin or command line
-p, --parallelism INTEGER	Number of parallel tasks to run (default: system capacity)
-h, --help	Show this message and exit

px superx

Manage PX Supervisor (superx) operations.

Usage: px superx [OPTIONS] COMMAND [ARGS]...

Commands

Command	Description
start	Start the daemon locally or on a cluster
stop	Stop the daemon locally or on a cluster
restart	Restart the daemon locally or on a cluster
status	Get daemon status locally or on a cluster
logs	Stream daemon logs locally or from a cluster

px superx start

Start the daemon locally or on a cluster.

Usage: px superx start [OPTIONS]

Options

Option	Description
-c, --cluster TEXT	Start supervisor on specified cluster
-h, --help	Show this message and exit

px superx stop

Stop the daemon locally or on a cluster.

Usage: px superx stop [OPTIONS]

Options

Option	Description
-c, --cluster TEXT	Stop supervisor on specified cluster
-h, --help	Show this message and exit

px superx restart

Restart the daemon locally or on a cluster.

Usage: px superx restart [OPTIONS]

Options

Option	Description
-c, --cluster TEXT	Restart supervisor on specified cluster
-h, --help	Show this message and exit

px superx status

Get daemon status locally or on a cluster.

Usage: px superx status [OPTIONS]

Options

Option	Description
-c, --cluster TEXT	Get supervisor status on specified cluster
-o, --output [console|json]	Output format (default: console)
-h, --help	Show this message and exit

px superx logs

Stream daemon logs locally or from a cluster.

Usage: px superx logs [OPTIONS]

Examples:

• px superx logs: show last 100 lines (local)
• px superx logs -f: follow logs in real-time
• px superx logs --cluster my-cluster -f: follow remote cluster logs
• px superx logs --since "1 hour ago": show logs from last hour

For advanced filtering, use journalctl directly (e.g. journalctl --user -u px-supervisor.service -p debug).

Options

Option	Description
-f, --follow	Follow log output (like tail -f)
-n, --lines INTEGER	Number of lines to show (default: 100)
--since TEXT	Show logs since (e.g. '1 hour ago', '2024-01-15')
-c, --cluster TEXT	Stream logs from specified cluster
-h, --help	Show this message and exit