CLI reference

Every portal command with its options and examples, generated from the CLI's own command tree.

Warnings and limits

Portal is open to anyone with an active Clusy account and a verified email address.
Some commands are for a controller you run yourself and are refused by https://gateway.clusy.io: changing settings (portal settings KEY VALUE, an Owner does it in the console's Settings) and portal audit --fix (an Owner cleans up leaks from the console's Machines page). See Settings.
portal run --secret NAME is refused by hosted Portal today: see Known issues.
portal deploy, portal dev and portal interrupt are for running and testing a controller of your own; portal interrupt sends a real provider interruption.
The project directory portal run uploads leaves out files over 100 MB and is refused over 500 MB: see Limits.

portal help and portal help COMMAND print this reference in your terminal, without signing in or connecting anything. Add --json to a command for output a script or coding tool can read.

Notes

JOB means a run ID, unique ID prefix or run name.
Run quotes machines first. Choose a returned spec and use --on SPEC to launch; --plan always previews.
Before launching, check effective quotas for the account, region and requested Spot/GPU compute.
Budgets and connection caps are optional. Set --budget or --cap only when you want a limit.
Add --json for scripts and coding tools. Help itself needs no sign-in or connection.
Guides, the full CLI reference and answers to common questions: https://portal.clusy.io/docs

Commands

Group	Command	What it does
Get started	`portal setup`	connect Portal to installed Claude Code and Codex and sign in through the browser
Get started	`portal login`	sign in: the browser approves this machine and the CLI gets a token of its own, never shown (or store a token made elsewhere, with --token-file PATH)
Get started	`portal connect`	connect a provider (alone: list them, and in your own terminal open the console's Connections page; --detect: the cloud CLIs signed in here; --from-cli: connect one with its CLI's login)
Choose and run	`portal prices`	compare compute quotes before choosing a machine
Choose and run	`portal run`	compare quotes, then run on a selected machine
Watch your work	`portal ps`	jobs and machines
Watch your work	`portal logs`	a job's output
Watch your work	`portal explain`	every policy decision about a job, and why
Watch your work	`portal dashboard`	open the console signed in, from your own terminal (elsewhere it prints the console's address); its Connect page while nothing but this machine is connected
Move, pause and collect	`portal move`	move a running job to another machine
Move, pause and collect	`portal suspend`	save a run's state and release its allocation
Move, pause and collect	`portal resume`	resume a suspended job when you choose, using --on for an exact destination
Move, pause and collect	`portal stop`	end a run and release its allocation
Move, pause and collect	`portal pull`	download a job's workspace after it ended
Move, pause and collect	`portal audit`	everything Portal runs, everywhere, and what leaked
Your machines	`portal machines`	list your enrolled machines
Your machines	`portal machine`	enroll or operate your own machine
Connections and secrets	`portal secrets`	secrets jobs can receive (--secret NAME)
Connections and secrets	`portal disconnect`	remove a named cloud connection
Settings and coding tools	`portal settings`	the controller's defaults: policies, fast path, encryption, baseline
Settings and coding tools	`portal update`	install the newest Portal CLI from your controller (its install command)
Settings and coding tools	`portal mcp`	an MCP server over stdio, for Claude Code and Codex
Settings and coding tools	`portal help`	usage guide and examples for Portal or one command
Explore, develop and test	`portal map`	the atlas: every offering and every way to carry a job between them
Explore, develop and test	`portal dev`	a controller on this machine, for development
Explore, develop and test	`portal interrupt`	for testing: a real spot interruption or preemption of a job's machine
Explore, develop and test	`portal deploy`	run the controller on EC2 in your AWS account; upgrade or destroy it, or recover its token
More	`portal rm`	delete ended jobs from your history (they leave every listing; costs still count them)

portal setup

connect Portal to installed Claude Code and Codex and sign in through the browser

usage: portal setup [-h] [--json] [--client {claude,codex}] [--root DIR] [--skip-login]
                    [--no-browser] [--device] [--reauth] [--prefer-portal | --no-prefer-portal]
                    [URL]

Argument	Required	What it is
`URL`	no	the controller (default: the current HTTPS controller or Portal)

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--client`	one of `claude`, `codex`	connect only this coding tool (repeatable; default: both installed tools)
`--root`	`DIR`	a project directory tools may upload (repeatable; default: the current safe directory)
`--skip-login`		register tools now; sign in on first use
`--no-browser`		show the sign-in page without opening a browser
`--device`		use device-code approval when a new sign-in is needed
`--reauth`		start a fresh sign-in instead of reusing the current one
`--prefer-portal`		explicitly prefer Portal for supported Python compute in your user instructions and install its skill
`--no-prefer-portal`		remove only Portal's managed compute preference and unchanged managed skill

Examples:

portal setup
portal setup --prefer-portal

Notes:

Setup reuses a valid sign-in and connects installed Claude Code and Codex.
--prefer-portal is an optional choice to install Portal-first compute guidance.

sign in: the browser approves this machine and the CLI gets a token of its own, never shown (or store a token made elsewhere, with --token-file PATH)

usage: portal login [-h] [--json] [--no-browser] [--device] [--reauth]
                    [--token T | --token-file PATH]
                    [URL]

Argument	Required	What it is
`URL`	no	the controller (default: the current one when it is HTTPS, else https://gateway.clusy.io)

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--no-browser`		print the console's approval page instead of opening it (open it on any device)
`--device`		use device-code approval when a new sign-in is needed
`--reauth`		start a fresh sign-in instead of reusing the current one
`--token`	`T`	unsafe on shared hosts: prefer piping the token on stdin (with --token-file -), or use --token-file PATH; kept for older scripts
`--token-file`	`PATH`	read the token from this file (- reads stdin)

Examples:

portal login

Notes:

Browser sign-in returns to the terminal automatically; --device or --no-browser uses a code backup.
Compare codes only for the device backup. No token needs to be pasted.

portal connect

connect a provider (alone: list them, and in your own terminal open the console's Connections page; --detect: the cloud CLIs signed in here; --from-cli: connect one with its CLI's login)

usage: portal connect [-h] [--json] [--file SECRETS_ENV] [--method METHOD] [--cap USD] [--ssh]
                      [--detect] [--from-cli] [--keys] [--secret] [--profile P] [--subscription S]
                      [--project P] [--federated] [--network N] [--subnetwork S]
                      [--private-network | --no-private-network] [--region R] [--location L]
                      [--yes] [--plan PLAN_ID]
                      [provider]

Argument	Required	What it is
`provider`	no	aws, azure, gcp, lambda, modal, e2b, local or a named connection

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--file`	`SECRETS_ENV`	import KEY=value lines (AWS_ACCESS_KEY_ID, MODAL_TOKEN_ID, PORTAL_SECRET_NAME, ...), or a native service account JSON file with gcp
`--method`		how to connect (asked when the provider has several)
`--cap`	`USD`	spend cap for the provider (with --file, for each provider the file connects)
`--ssh`		with --detect, include concrete SSH config aliases
`--detect`		the cloud CLIs installed and signed in on this machine, and which Portal can connect (it only reads)
`--from-cli`		with aws, azure, gcp, modal or lambda: connect with that CLI's login, in your own account, after listing every step and asking. AWS gets a role the controller assumes and Azure a federated credential (nothing stored a thief could use); Google Cloud the approved federation when the controller offers it, else a key; Modal and Lambda a token, sealed on the controller
`--keys`		with aws or gcp --from-cli: make a dedicated IAM user and access key (AWS) or a service account key (Google Cloud), sealed on the controller, instead of the role or the federation
`--secret`		with azure --from-cli: make a client secret (sealed on the controller) instead of the federated credential
`--profile`	`P`	with aws --from-cli: the AWS CLI profile whose login is used
`--subscription`	`S`	with azure --from-cli: the subscription, by name or id
`--project`	`P`	with gcp --from-cli: the project ID (default: gcloud's current project)
`--federated`		with gcp --from-cli: pair the controller's approved AWS identity without a service account key
`--network`	`N`	with gcp --from-cli: reuse this existing network (name or resource path)
`--subnetwork`	`S`	with gcp --from-cli: existing subnetwork resource path in --region
`--private-network`, `--no-private-network`		with gcp --from-cli: omit external IPs; the existing network must provide NAT or another outbound path
`--region`	`R`	with aws or gcp --from-cli: the connection's region (GCP default us-central1)
`--location`	`L`	with azure --from-cli: where the resource group soma goes (default eastus)
`--yes`		with --from-cli: go ahead without asking (the steps are still printed first)
`--plan`	`PLAN_ID`	with --from-cli: go ahead only with the plan of that id (the plan_id an earlier --json printed); other steps are printed, and nothing is created

Examples:

portal connect --detect
portal connect aws --from-cli
portal connect gcp --from-cli --federated
portal connect --json

Notes:

--detect only reads local cloud CLI sign-ins. --from-cli shows steps and asks before creating access.
For an operator-approved GCP binding, --federated pairs AWS identity without a service account key.
A connected account does not establish usable quota. Check account, region, family and Spot/GPU limits.
Leave --cap unset unless you want a connection spending limit.

portal prices

compare compute quotes before choosing a machine

usage: portal prices [-h] [--json] [--gpu L4|24G|any] [--gpus N] [--cpus N] [--mem GB]
                     [--spot | --no-spot] [--providers NAMES]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--gpu`	`L4\|24G\|any`	a GPU model, a memory per GPU, or any GPU
`--gpus`	`N`	GPUs per machine
`--cpus`	`N`	at least N vCPUs
`--mem`	`GB`	at least this much memory
`--spot`, `--no-spot`		spot only, or never spot (default: spot when offered)
`--providers`	`NAMES`	only these providers, e.g. aws,modal

Examples:

portal prices --gpu T4
portal prices --cpus 4 --mem 8 --no-spot

portal run

compare quotes, then run on a selected machine

usage: portal run [options] SCRIPT [ARGS...]

Argument	Required	What it is
`script`	yes	a Python file in this directory (the directory is uploaded with it)

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--gpu`	`L4\|24G\|any`	a GPU model, a memory per GPU, or any GPU
`--gpus`	`N`	GPUs per machine
`--cpus`	`N`	at least N vCPUs
`--mem`	`GB`	at least this much memory
`--spot`, `--no-spot`		spot only, or never spot (default: spot when offered)
`--providers`	`NAMES`	only these providers, e.g. aws,modal
`--on`	`SPEC`	launch on the exact spec selected from the returned quotes
`--gpu-fallback`	one of `none`, `same_provider`, `any`	when the GPU asked for is not scheduled within Portal's bounded wait (5 min on Modal): run on the same provider's cheapest other GPU (same_provider) or any connected provider's (any); none, the default, ends the job with the choices instead
`--budget`	`USD`	A budget suspends the run when it is spent: its machine is released and the program stops until someone resumes it. Leave it unset unless a spending limit is wanted.
`--name`		a name to refer to the job by
`--project`	`NAME`	required to launch, optional for quotes: portal ps and the console group jobs and their cost estimates and comparisons by it
`--env`	`K=V`	an environment variable for the script
`--secret`	`NAME`	a stored secret, as an environment variable
`-d`, `--detach`		with --on, return once the job is queued
`--plan`		only show quotes, including when --on selects a machine
`--no-return`		do not move back to spot when that pays
`--rightsize`	one of `on_move`, `active`, `off`	size CPU and memory from use: at the next move (default), also by moving, or never
`--no-cheaper`		never move by itself to a cheaper offer
`--no-evacuate`		no automatic checkpoint and suspension on a spot or preemption notice (the spot policy off)
`--policy`	`KEY=VALUE`	a policy for this job over portal.yaml, e.g. cheaper=off, rightsize=off, idle.after_min=60

Examples:

portal run train.py --gpu T4
portal run train.py --gpu T4 --on modal:gpu=T4 -d --project training
portal run train.py --cpus 4 --mem 8
portal run train.py --gpu T4 --on modal:gpu=T4 -d -- --epochs 10

Notes:

Without --on, compare quotes without uploading the project or starting a job.
Select a returned offer's exact spec with --on SPEC. --plan keeps even a selected offer in preview.
Launching requires --project NAME (1 to 100 characters). Quotes may omit it; budgets stay optional.
An exact --on pins the run to that destination; moves and resumes keep their own choices.
A selected launch uploads the project directory; -d returns after the job is queued.
Put script arguments after --. Ctrl-C detaches from streaming output; it does not stop the cloud run.
--gpu accepts a model such as T4, memory such as 24G, or any. --spot requires Spot; --no-spot excludes it.
Keep secrets out of --env: use portal secrets set NAME, then --secret NAME.
A --budget is optional and suspends a run when spent. Check effective quota before launching.

portal ps

jobs and machines

usage: portal ps [-h] [--json] [-a]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`-a`, `--all`		every job, not only active and recent ones

Examples:

portal ps
portal ps --all

portal logs

a job's output

usage: portal logs [-h] [--json] [-f] [-n N] job

Argument	Required	What it is
`job`	yes	a job id, a unique start of one, or a job name

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`-f`, `--follow`		keep printing until the job ends
`-n`, `--tail`	`N`	only the last N lines

Examples:

portal logs JOB --tail 50
portal logs JOB --follow

portal explain

every policy decision about a job, and why

usage: portal explain [-h] [--json] job

Argument	Required	What it is
`job`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Examples:

portal explain JOB

portal dashboard

open the console signed in, from your own terminal (elsewhere it prints the console's address); its Connect page while nothing but this machine is connected

usage: portal dashboard [-h] [--json] [--link]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--link`		print (with --json, return) the one-time sign-in link instead of opening a browser: it signs in whoever opens it first, so keep it out of chats and logs

Examples:

portal dashboard

Notes:

Run this in your own terminal. Do not share a one-time sign-in link in a chat or log.

portal move

move a running job to another machine

usage: portal move [-h] [--json] [--to SPEC] [--gpu-fallback MODE] [--gpu L4|24G|any] [--gpus N]
                   [--cpus N] [--mem GB] [--providers NAMES] [--plan] [--no-wait] [--wait]
                   job

Argument	Required	What it is
`job`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--to`	`SPEC`	exactly here, e.g. modal:gpu=L4
`--gpu-fallback`	one of `none`, `same_provider`, `any`	with --to: when that GPU is not scheduled within Portal's bounded wait, move to the same provider's cheapest other GPU (same_provider) or any connected provider's (any) instead; none, the default, leaves the job where it runs
`--gpu`	`L4\|24G\|any`	a GPU model, a memory per GPU, or any GPU
`--gpus`	`N`	GPUs per machine
`--cpus`	`N`	at least N vCPUs
`--mem`	`GB`	at least this much memory
`--providers`	`NAMES`	only these providers, e.g. aws,modal
`--plan`		only show where it would go and at what price
`--no-wait`		return once the move is accepted instead of waiting up to 15 s for its outcome
`--wait`		with --json, wait up to 15 s for the outcome (without --json that is the default)

Examples:

portal move JOB --gpu L4 --plan
portal move JOB --gpu L4

Notes:

--plan previews the destination; without it, move pauses and transfers the running program.
Use either --to SPEC or hardware requirements, not both.
move waits up to 15 s and prints the outcome: where it landed, or why it did not. With --no-wait it returns once the move is accepted; portal ps shows when it lands, portal events JOB why if it does not.
--json returns once the move is accepted (outcome accepted) unless --wait is given, which follows the move as above (outcome landed, aborted with its reason, parked or pending).
A job whose program has already exited is not moved: the request is refused with the job's end.

portal suspend

save a run's state and release its allocation

usage: portal suspend [-h] [--json] job

Argument	Required	What it is
`job`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Examples:

portal suspend JOB

Notes:

Suspend saves the run's state and releases its allocation. Resume continues it later.

portal resume

resume a suspended job when you choose, using --on for an exact destination

usage: portal resume [-h] [--json] [--on SPEC] [--gpu L4|24G|any] [--gpus N] [--cpus N] [--mem GB]
                     [--providers NAMES]
                     job

Argument	Required	What it is
`job`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--on`	`SPEC`	exactly here instead of the best offer
`--gpu`	`L4\|24G\|any`	a GPU model, a memory per GPU, or any GPU
`--gpus`	`N`	GPUs per machine
`--cpus`	`N`	at least N vCPUs
`--mem`	`GB`	at least this much memory
`--providers`	`NAMES`	only these providers, e.g. aws,modal

Examples:

portal resume JOB --gpu T4
portal resume JOB --on modal:gpu=T4

Notes:

Resume only when you want a suspended run to use compute again.
Use either --on SPEC or hardware requirements, not both.

portal stop

end a run and release its allocation

usage: portal stop [-h] [--json] job

Argument	Required	What it is
`job`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Examples:

portal stop JOB

Notes:

Stop ends the run and releases its allocation. An enrolled personal computer is not powered off.

portal pull

download a job's workspace after it ended

usage: portal pull [-h] [--json] job [dir]

Argument	Required	What it is
`job`	yes
`dir`	no	where to unpack it (default: a directory named after the job)

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Examples:

portal pull JOB ./results

portal audit

everything Portal runs, everywhere, and what leaked

usage: portal audit [-h] [--json] [--fix] [--untracked]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--fix`		terminate this controller's leaked resources, then audit again
`--untracked`		with --fix, ALSO terminate Portal-tagged machines that no controller of yours tracks. CAREFUL: when several controllers share an account, those can be another controller's running jobs

Examples:

portal audit
portal audit --fix

Notes:

The default only checks resources. Review its findings before using --fix to terminate leaks.
--untracked may affect another controller's resources and needs explicit review.

portal machines

list your enrolled machines

usage: portal machines [-h] [--json]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Examples:

portal machines

portal machine

enroll or operate your own machine

usage: portal machine [-h] [--json] {command,add,rm,join,run,status,uninstall} ...

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Subcommands: portal machine command, portal machine add, portal machine rm, portal machine join, portal machine run, portal machine status, portal machine uninstall.

Examples:

portal machine command --name workstation
portal machine status

Notes:

Run the returned installation command on your computer, then approve its pairing code in Portal.
Use --on machine.NAME to target an approved machine. Releasing a run never powers that computer off.

portal machine command

Create a short-lived enrollment command for your own computer.

usage: portal machine command [-h] [--json] [--name NAME]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--name`

Examples:

portal machine command --name workstation

portal machine add

Install an agent through a reviewed SSH host.

usage: portal machine add [-h] [--json] [--name NAME] [--yes] host

Argument	Required	What it is
`host`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--name`
`--yes`

Examples:

portal machine add gpu-host --name workstation

portal machine rm

Remove an enrolled machine.

usage: portal machine rm [-h] [--json] id

Argument	Required	What it is
`id`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Examples:

portal machine rm MACHINE_ID

portal machine join

Enroll this computer using an installation code read from a file or stdin.

usage: portal machine join [-h] [--json] [--name NAME] [--system] --code-file CODE_FILE
                           [--no-service] [--insecure-http] [--ssh-host-key SSH_HOST_KEY]
                           url

Argument	Required	What it is
`url`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--name`
`--system`
`--code-file`
`--no-service`
`--insecure-http`
`--ssh-host-key`

Examples:

portal machine join https://gateway.clusy.io --code-file -

portal machine run

Run this computer's Portal agent.

usage: portal machine run [-h] [--json] [--system]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--system`

Examples:

portal machine run

portal machine status

Show this computer's Portal agent status.

usage: portal machine status [-h] [--json] [--system]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--system`

Examples:

portal machine status

portal machine uninstall

Uninstall this computer's Portal agent.

usage: portal machine uninstall [-h] [--json] [--system]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--system`

Examples:

portal machine uninstall

portal secrets

secrets jobs can receive (--secret NAME)

usage: portal secrets [-h] [--json] ACTION ...

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Subcommands: portal secrets set, portal secrets rm.

Examples:

portal secrets
portal secrets set HF_TOKEN
portal run train.py --secret HF_TOKEN -d

Notes:

Values are read privately from the terminal or stdin. Pass stored secrets to runs by name.

portal secrets set

store a secret from the terminal, stdin or a named environment variable

usage: portal secrets set [-h] [--json] [--from-env ENV] name

Argument	Required	What it is
`name`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--from-env`	`ENV`	read the value from this local environment variable without printing it

Examples:

portal secrets set HF_TOKEN
portal secrets set HF_TOKEN --from-env HF_TOKEN

portal secrets rm

remove a secret

usage: portal secrets rm [-h] [--json] name

Argument	Required	What it is
`name`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Examples:

portal secrets rm HF_TOKEN

portal disconnect

remove a named cloud connection

usage: portal disconnect [-h] [--json] provider

Argument	Required	What it is
`provider`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Examples:

portal disconnect modal

portal settings

the controller's defaults: policies, fast path, encryption, baseline

usage: portal settings [-h] [--json] [KEY] [VALUE]

Argument	Required	What it is
`KEY`	no	one setting, e.g. spot.on or return.min_saving_pct
`VALUE`	no	its new value (null clears it)

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Examples:

portal settings
portal settings spot.on

portal update

install the newest Portal CLI from your controller (its install command)

usage: portal update [-h] [--json] [--check | --force]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--check`		only say whether an update is available
`--force`		install the served build even when it is this one

Examples:

portal update
portal update --check

Notes:

It runs your controller's install command: your sign-in and coding tool setup stay, and Portal's skill is refreshed for the tools you chose to prefer Portal in. Restart those tools afterwards.
Other commands check once a day and say when an update is available; PORTAL_NO_UPDATE_CHECK=1 turns that off.

portal mcp

an MCP server over stdio, for Claude Code and Codex

usage: portal mcp [-h] [--json] [--root DIR]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--root`	`DIR`	a directory run may also upload projects from, beside the one the server starts in (repeatable)

Examples:

portal mcp --root /path/to/project

Notes:

portal setup registers this server with installed coding tools; they normally start it for you.

portal help

usage guide and examples for Portal or one command

usage: portal help [-h] [--json] [COMMAND ...]

Argument	Required	What it is
`COMMAND`	no	a command or nested command, e.g. run or machine command

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Examples:

portal help run
portal help machine command

portal map

the atlas: every offering and every way to carry a job between them

usage: portal map [-h] [--json] [--no-open]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--no-open`		write the page, do not open it

Examples:

portal map --no-open

Notes:

Explore provider offerings and supported move routes. A map entry does not guarantee account quota or runtime compatibility.

portal dev

a controller on this machine, for development

usage: portal dev [-h] [--json] ACTION ...

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Subcommands: portal dev up, portal dev down.

Examples:

portal dev up
portal dev down

portal dev up

start it

usage: portal dev up [-h] [--json] [--docker] [--port N]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--docker`		in a container instead of a process
`--port`	`N`	on this port of 127.0.0.1 (default 7700)

Examples:

portal dev up --docker

portal dev down

stop it

usage: portal dev down [-h] [--json]

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else

Examples:

portal dev down

portal interrupt

for testing: a real spot interruption or preemption of a job's machine

usage: portal interrupt [-h] [--json] [--after TIME] job

Argument	Required	What it is
`job`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--after`	`TIME`	EC2 interruption notice, e.g. 2m (default: 2m); a Fargate stop begins at once

Examples:

portal interrupt JOB --after 2m

Notes:

Testing only: this sends a real provider interruption to a job's machine.

portal deploy

run the controller on EC2 in your AWS account; upgrade or destroy it, or recover its token

usage: portal deploy [-h] [--json] [--domain DOMAIN] [--console-origin CONSOLE_ORIGIN]
                     [--region REGION] [--instance-type INSTANCE_TYPE] [--node-image IMAGE]
                     [--upgrade | --destroy | --recover-token] [--purge] [--release-address]
                     [--force] [--show]
                     {aws}

Argument	Required	What it is
`{aws}`	yes

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--domain`		the controller's address (default gateway.clusy.io)
`--console-origin`		an additional HTTPS browser origin; API and nodes keep --domain (preserved when omitted; an empty value removes it)
`--region`		the AWS region (default us-east-1)
`--instance-type`		the EC2 instance type (default t4g.small)
`--node-image`	`IMAGE`	the public node image Fargate and Container Apps run
`--upgrade`		a new controller image and a restart
`--destroy`		stop and terminate it; its data, address, key and token stay (refused while jobs run)
`--recover-token`		point this machine's CLI at the deployed controller again, its token read from SSM
`--purge`		with --destroy: also delete ops/ in R2, the data volume, the SSM parameters and the KMS key
`--release-address`		with --destroy --purge: release the Elastic IP too (refused while the domain points at it)
`--force`		with --upgrade: rebuild an unchanged build; with --destroy: even while jobs run
`--show`		with --recover-token: print the token

Examples:

portal deploy aws --domain portal.example.com

Notes:

Operator command: manage a controller in your own AWS account. Hosted Portal users normally do not need it.

portal rm

delete ended jobs from your history (they leave every listing; costs still count them)

usage: portal rm [-h] [--json] [--ended] [--project NAME] [--before TIME] [--yes] [JOB ...]

Argument	Required	What it is
`JOB`	no	the jobs to delete, by id, name or id prefix

Option	Value	What it does
`--json`		machine output: one JSON document per line, nothing else
`--ended`		every ended job (with --project or --before to narrow it)
`--project`	`NAME`	with --ended: only this project's jobs
`--before`	`TIME`	with --ended: only jobs created before this (an ISO date or time, UTC)
`--yes`		delete what the plan lists without asking

Examples:

portal rm JOB
portal rm --ended --project old-sweeps
portal rm --ended --before 2026-10-01 --yes

Notes:

Only ended runs can be deleted: they leave every listing, and their costs and savings still count.
It shows what would go first, naming runs that could still be continued from kept checkpoints, and asks; --yes deletes what it shows without asking.

On this page