CLI Reference
Every command, flag, and option for the particle CLI.
Particles
Create, manage, and connect to cloud VMs.
particle run
Create and start a new particle. If no account exists, one is auto-created from your SSH key. The particle will automatically stop after 2 minutes of inactivity.
$ particle run myapp --size p2 Creating particle 'myapp' (p2: 2 vCPUs, 4GB RAM, 20GB disk)... ✓ Particle 'myapp' is running
| Flag | Default | Description |
|---|---|---|
--size <tier> | p1 | VM size tier (p1–p5). See Pricing for specs. |
--image <image> | ubuntu-24.04 | Base OS image. Run particle images to see available options. |
--init <script> | — | Path to a shell script that runs on first boot (e.g., install dependencies, clone repos). |
particle images
List available OS images that can be used with particle run --image.
$ particle images NAME DESCRIPTION DEFAULT ubuntu-24.04 Ubuntu 24.04 LTS * debian-12 Debian 12 (Bookworm)
particle list
List all particles on your account with their status, size, and URL.
$ particle list NAME SIZE STATUS URL myapp p2 running myapp.runparticle.com staging p1 stopped staging.runparticle.com
particle stop
Stop a running particle. Disk is preserved. You're only charged the stopped storage rate.
$ particle stop myapp ✓ Particle 'myapp' stopped
particle start
Start a stopped particle. Resumes from where it left off with disk intact.
$ particle start myapp ✓ Particle 'myapp' is running
particle delete
Permanently delete a particle and its disk. This action cannot be undone.
$ particle delete myapp Are you sure? This will permanently delete 'myapp' and its disk. [y/N] y ✓ Particle 'myapp' deleted
particle duplicate
Clone a stopped particle to a new one. Creates an exact copy of the disk.
$ particle duplicate myapp myapp-copy Cloning 'myapp' → 'myapp-copy'... ✓ Particle 'myapp-copy' created (stopped)
particle rebuild
Replace the particle's disk with a fresh copy of its base image. Erases all data but keeps the name, IP, and account association. The particle must be stopped (or will be stopped with confirmation).
$ particle rebuild myapp -y Rebuilt particle myapp
particle rename
Rename a particle. Updates the HTTP route to <new>.runparticle.com.
$ particle rename myapp production ✓ Renamed 'myapp' → 'production'
particle ssh
Open an SSH session into a running particle. You get a full root shell.
$ particle ssh myapp Connecting to myapp... Welcome to Ubuntu 24.04 LTS root@myapp:~# _
particle ssh-config
Generate SSH config entries for your particles. Output can be pasted into ~/.ssh/config or written directly with --write. Enables one-command IDE integration with VS Code Remote-SSH, JetBrains Gateway, and other SSH tools.
$ particle ssh-config # particle: myapp Host myapp.particle HostName runparticle.com User myapp Port 22 ...
$ particle ssh-config --write ✓ myapp.particle Written to /home/user/.ssh/config
particle forward
Forward one or more local ports to a particle using SSH port forwarding. Useful for accessing databases, dev servers, or any TCP service running inside a particle.
$ particle forward myapp 8080:3000 Forwarding 127.0.0.1:8080 → myapp:3000 Press Ctrl+C to stop
Forward multiple ports at once:
$ particle forward myapp 5432 8080 Forwarding 127.0.0.1:5432 → myapp:5432 Forwarding 127.0.0.1:8080 → myapp:8080 Press Ctrl+C to stop
| Flag | Default | Description |
|---|---|---|
-p, --port <port> | 22 | SSH port on the server. |
--bind <addr> | 127.0.0.1 | Bind address for local ports. |
particle exec
Execute a command on a running particle via SSH and print the output. Use -- to separate the command from particle flags.
$ particle exec myapp -- apt update && apt install -y nginx Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease Reading package lists... Done Setting up nginx (1.24.0) ... ✓ Command exited with code 0
particle cp
Copy files to or from a particle using SCP. Use <name>:<path> syntax for remote paths.
$ particle cp ./app.tar.gz myapp:/tmp/ app.tar.gz 100% 4.2MB 12.1MB/s 00:00
$ particle cp myapp:/var/log/app.log ./ app.log 100% 128KB 8.5MB/s 00:00
| Flag | Default | Description |
|---|---|---|
-r, --recursive | — | Recursively copy directories. |
-p, --port <port> | 22 | SSH port on the server. |
particle open
Open the particle's HTTP URL in your default browser. Use --print to print the URL without opening the browser.
$ particle open myapp https://myapp-a1b2c3d4.runparticle.com
particle resize
Resize a particle to a different size tier. The particle must be stopped first.
$ particle resize myapp p4 Resized myapp to p4
| Argument | Description |
|---|---|
<size> | Target size tier: p1, p2, p4, p8, p16. See Pricing for specs. |
particle port
Set the default HTTP port for a particle. This is the port the HTTP proxy forwards traffic to when accessed via <name>-<acct>.runparticle.com. The default is port 80. Note: you can also access any port directly via <name>-<port>-<acct>.runparticle.com without changing this setting.
$ particle port myapp 8080 Set HTTP port for myapp to 8080
| Argument | Description |
|---|---|
<port> | Port number (1–65535). |
particle idle
Set the idle policy for a particle. Controls what happens when no SSH or HTTP activity is detected.
$ particle idle myapp on ✓ Idle policy for 'myapp' set to: on (always running)
| Policy | Behavior |
|---|---|
sleep | Stop after 2 minutes of inactivity. Wakes on SSH connect or HTTP request. Default. |
none | No idle policy. Particle runs until manually stopped. |
on | Keep running 24/7, never auto-stop. |
schedule | Set active hours. Runs during schedule, stops otherwise. |
particle logs
View the serial console output of a particle. Useful for debugging boot issues.
$ particle logs myapp [ 0.000000] Linux version 6.1.0 ... [ 0.123456] Command line: console=ttyS0 [ 1.234567] EXT4-fs: mounted filesystem [ 2.345678] systemd[1]: Started OpenSSH server.
Stream logs in real-time with --follow:
$ particle logs myapp -f [ 2.345678] systemd[1]: Started OpenSSH server. [ 12.456789] myapp: listening on :8080 █ streaming...
| Flag | Description |
|---|---|
--follow, -f | Stream logs in real-time (like tail -f). Uses SSE for live updates. |
particle status
Show detailed information about a particle including size, status, uptime, and idle policy.
$ particle status myapp Name: myapp Size: p2 (2 vCPUs, 4GB RAM, 20GB disk) Status: running Uptime: 3h 42m Idle: - URL: myapp.runparticle.com Internal IP: 10.0.0.2
SSH Keys
Manage the SSH keys associated with your account.
particle key list
List all SSH keys on your account.
$ particle key list FINGERPRINT ADDED SHA256:a1b2c3d4e5f6... 2026-03-01 SHA256:x7y8z9w0v1u2... 2026-03-05
particle key add
Add an SSH public key to your account. Use this to access your particles from multiple machines.
$ particle key add ~/.ssh/id_ed25519.pub ✓ Key added: SHA256:x7y8z9...
particle key remove
Remove an SSH key from your account.
$ particle key remove SHA256:x7y8z9w0v1u2 ✓ Key removed
particle account rotate-key
Rotate your API key. Generates a new key and invalidates the old one. The new key is saved to ~/.config/particle/credentials.
$ particle account rotate-key This will invalidate your current API key. Continue? [y/N] y New API key: rp_k1_n3w4k5e6y7... Config updated at ~/.config/particle/credentials
Snapshots
Create, list, restore, and delete point-in-time snapshots of a particle's disk.
particle snapshot create
Create a named snapshot of a particle's disk.
$ particle snapshot create myapp before-deploy ✓ Snapshot 'before-deploy' created
particle snapshot list
List all snapshots for a particle.
$ particle snapshot list myapp NAME SIZE CREATED before-deploy 2.1 GB 2026-03-07 10:30 initial-setup 1.8 GB 2026-03-05 14:00
particle snapshot restore
Restore a snapshot. The particle must be stopped before restoring.
$ particle snapshot restore myapp before-deploy ✓ Snapshot 'before-deploy' restored
particle snapshot delete
Delete a snapshot.
$ particle snapshot delete myapp before-deploy ✓ Snapshot 'before-deploy' deleted
Custom Domains
Set a custom domain for your particle instead of the default <name>.runparticle.com subdomain.
particle domain set
Set a custom domain for a particle. Point your domain's DNS to runparticle.com via a CNAME record.
$ particle domain set myapp app.example.com ✓ Custom domain set: app.example.com → myapp
particle domain clear
Remove the custom domain from a particle, reverting to the default <name>.runparticle.com URL.
$ particle domain clear myapp ✓ Custom domain removed from 'myapp'
Account & Billing
Manage your account, balance, and payment history.
particle account
Show your account info, current balance, and usage summary.
$ particle account Account: SHA256:a1b2c3... Balance: $9.76 Particles: 1 running, 1 stopped Burn rate: $0.024/hr
particle usage
Show per-particle usage breakdown including compute hours and spend.
$ particle usage PARTICLE SIZE STATUS COMPUTE TOTAL myapp p2 running 48.2h $1.16 staging p1 stopped 12.0h $0.14 ────────────────────────────────────────────────────── $1.30
| Flag | Default | Description |
|---|---|---|
--period <period> | month | Time period: day, week, month, all |
particle topup
Generate a Stripe payment link to add funds to your account. Opens in your default browser.
$ particle topup 25 Opening Stripe checkout in your browser... Waiting for payment confirmation... ✓ $25.00 added to your account
| Argument | Default | Description |
|---|---|---|
[amount] | 10 | Amount in USD to add to your balance. |
particle login
Recover access to your account via your recovery email. Use this when accessing your account from a new machine without your original SSH key.
$ particle login Enter your recovery email: user@example.com Check your email for a verification link... ✓ Logged in. API key stored in ~/.config/particle/credentials
particle history
Show your transaction history including top-ups and usage charges.
$ particle history DATE TYPE AMOUNT BALANCE 2026-03-06 topup +$25.00 $25.00 2026-03-06 usage -$0.24 $24.76 2026-03-05 topup +$10.00 $10.00
particle upgrade
Update the particle CLI to the latest version. Downloads the new binary and replaces the current one.
$ particle upgrade Checking for updates... Downloading particle v0.2.0... ✓ Updated to v0.2.0