Skip to main content

Petabyte CLI

petabyte is the command line for the Petabyte GPU marketplace — for buyers who rent verified GPUs, for sellers who earn with their own hardware, and for anyone who wants an AI model on their machine. Install → sign in → choose buyer or seller → go.

pip install -U petabyte-client        # the command it installs is `petabyte`
petabyte login                        # sign in with your browser — no password ever touches the CLI
petabyte --me                         # your dashboard: account, wallet, what's running, agent, system

Run petabyte on its own for a guided menu, or petabyte --help for the grouped command list.

5-minute Seller Quickstart

Turn an idle GPU (or CPU) into income. On the machine you want to sell:

pip install -U petabyte-client
petabyte login                 # browser sign-in
petabyte --install-agent       # guided wizard: checks the system, mints a node key, runs the official installer
petabyte --run-agent           # starts the seller agent and follows it coming online
petabyte --me                  # watch the node, the earning rate and your wallet

The wizard checks Python, Docker, the GPU and the network first, tells you exactly what to fix if something is missing, then downloads the official installer to a file from your Petabyte host (never curl | bash), shows what it will do (it needs administrator rights: Docker, the NVIDIA container toolkit, a systemd service) and asks before running it. The node key it creates goes to the installer through the environment only — it is never printed or logged.

Later: petabyte --kill-agent stops the agent safely (it warns if a job is running), petabyte agent status / petabyte agent logs show what it is doing, petabyte earnings and petabyte node status <id> show the money and the node.

  • Linux: the agent is the petabyte-agent systemd service under /opt/petabyte-agent.
  • Windows: the same service inside the agent's own Petabyte WSL2 distro the installer sets up (run the install from an Administrator PowerShell).
  • macOS: the seller agent is not supported yet; buying works everywhere.

Buyer Quickstart

petabyte login
petabyte deposit 20                                   # add funds (test credit in the sandbox)
petabyte specs                                        # available GPUs; use the ID column with --spec
petabyte launch ollama --hours 2                      # choose a GPU from the interactive picker
petabyte run train.ipynb --gpu "RTX 4090" --hours 1   # run a notebook / .py on a rented GPU
petabyte instances                                         # what's running, recent bookings
petabyte ssh                                          # one-time: make this computer able to reach your VMs
petabyte ssh <vm-id>                                  # then connect
petabyte ask "explain attention" --model llama3.2     # pay-per-token inference (OpenAI-compatible)

To select a specific host, copy its ID from petabyte specs into petabyte launch <template> --spec <ID> --hours 1. For example, if the table shows ID 246:

petabyte launch fedora-kde --spec 246 --hours 1 --max-price 0.13

From client version 0.4.9, launch --spec also accepts the marketplace's public host ID.

From 0.5.0, spot (interruptible, billed per second) rentals:

petabyte launch jupyter --spot --max-price 0.50 --hours 1                    # now, or fail
petabyte launch jupyter --spot --gpu a100-80gb --max-price 1.20 --within 24h # wait for one
petabyte orders                 # waiting orders
petabyte orders cancel <id>

A waiting spot order starts (and emails you) as soon as a matching host is idle, and resumes from its checkpoint after an interruption until it expires. --spec ID and --gateway us|sa pin a host or gateway. You do not need to translate a public ID into a number. Without --spec, an interactive terminal shows a numbered GPU picker; scripts and --json let the server select a matching host.

Commands

Group Command What it does
Account --me / me dashboard: identity, wallet, current workflow, agent, expected return (estimates labelled), local CPU/RAM/GPU
login browser device-flow sign-in; saves a token in ~/.petabyte/cli.json (0600)
wallet · deposit <usd> · activity balance & earnings · add funds · recent notifications
doctor diagnoses Python, network, API, account, Docker, GPU, agent — with the command to run next
Seller --install-agent guided seller setup (--sell gpu|cpu|all, --price, --dry-run, --yes)
--run-agent preflight → start the service → status panel → follow the log (--no-follow)
--kill-agent graceful stop; warns about active jobs (--force to stop anyway); idempotent
agent status|logs|install|start|stop the same as subcommands
earnings · node status <id> · node sync-models <id> payouts · one node in detail · report cached models
Buyer specs · launch <template> · run <file> · jobs rent and run
ssh [vm-id] set this computer up to reach your VMs, then connect (--status, --print, --key, --new-key)
ask "<prompt>" · render · transcode · vpn <booking> inference · Blender · NVENC · WireGuard config
Models model search|info|pull|list|inspect|remove · pull <id> · run <model-id> local model hub (no account needed)
System --version · --json · --verbose · --api <url> · -y/--yes version & update status · machine-readable output · full error detail · another host · assume yes

Every subcommand keeps its full option list under petabyte <command> --help.

Output, config & environment

  • Rich terminal UI (panels, tables, spinners) on a real terminal; plain, aligned text on a pipe, in CI, under NO_COLOR=1 / PETABYTE_COLOR=never / TERM=dumb, or when rich is missing. The words are the same in both. PETABYTE_UI=plain|rich forces a renderer, PETABYTE_ASCII=1 avoids Unicode symbols, PETABYTE_NONINTERACTIVE=1 makes every prompt take its default.
  • --json (before the command) gives machine-readable output for --me, doctor, wallet, specs, earnings, jobs, activity, agent status, --version — never coloured, never chatty.
  • Update check: once a day, on an interactive terminal only, the CLI asks PyPI (1.5 s timeout) whether a newer petabyte-client exists and prints a one-line hint. It never blocks, never fails a command, and is skipped in CI or with PETABYTE_NO_UPDATE_CHECK=1. Python < 3.9 gets a clear unsupported-version message.
  • API host: --api <url> > PETABYTE_API_URL > the saved file > https://petabyte.market. PETABYTE_CONFIG=/path/cli.json isolates the saved token (CI, tests).
  • Auth: the saved token from petabyte login, or PETABYTE_TOKEN, or an account-scoped API key in PETABYTE_API_KEY (sent as X-API-KEY). petabyte ask uses an inference-scoped key.
  • Errors are written for humans — what happened, why, what to run next — with the technical detail dimmed last; --verbose adds the traceback. Secrets (tokens, keys, node keys) never appear.

When something is off

petabyte doctor

For developers

From a source checkout: python cli/petabyte.py <cmd> (the product layer lives in cli/petabyte_cli/: ui.py, version_check.py, sysinfo.py, api.py, dashboard.py, agent.py, agent_cmds.py, doctor.py, help.py, menu.py). Tests: python cli/petabyte_cli_test.py (no server), python cli/cli_ui_test.py, python cli/cli_petabyte_test.py (boots a local API). The package is built from the repo-root pyproject.toml (name = "petabyte-client", dependencies httpx, rich, tqdm; optional extra system = psutil for live CPU/RAM) and mirrored to the public repo by scripts/build_cli_package.py.

Dashboard (web)

Served by the API at / — live nodes/jobs stats, wallet + deposit, the GPU inventory with a live $/hr-vs-AWS savings column, and one-click job runs. Both the web console and the CLI need an attested, online seller node (run the agent) to actually execute jobs.

Metadata

Release files for petabyte-client 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for petabyte-client 0.5.0
File Size Uploaded Provenance Actions
petabyte_client-0.5.0.tar.gz 150.3 kB Without provenance Details for petabyte_client-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for petabyte-client 0.5.0
File Interpreter ABI Platform Actions
petabyte_client-0.5.0-py3-none-any.whl Python 3 none any Details for petabyte_client-0.5.0-py3-none-any.whl

Total release size: 320.9 kB

Release files / petabyte_client-0.5.0.tar.gz

Download URL petabyte_client-0.5.0.tar.gz
Size 150.3 kB
Tags Source
SHA-256 checksum
How to use checksums
bf55470d2c165e021b90039e28170d7fff4d9ec79c789f80df51640e2dcdef99
BLAKE2b-256 checksum
How to use checksums
3911c1851eb57c41277ef16b48116c846bf13b5f62bcd3d104d5588a775a3aa1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / petabyte_client-0.5.0-py3-none-any.whl

Download URL petabyte_client-0.5.0-py3-none-any.whl
Size 170.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ac2fc3476d2e8c2d588b1f4147c7b4264d242a21ae8c0dac50bd19d1f1dce0b2
BLAKE2b-256 checksum
How to use checksums
ef024fdc85535206da58672b9c0dedb6f76a7de70b67ff0d4e19ce015af69649
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for petabyte-client 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page