CLI reference

Every command accepts -h / --help.

Global options

These go before the command: freepod --verbose deploy.

Option	Description
--verbose	show extra detail
--quiet	suppress progress and diagnostics; results and errors still appear
--timeout SECONDS	how long to wait for the current operation before giving up (defaults: login 300s, build 1800s, rollout 600s)
--version	Show the version and exit.

freepod bucket

freepod bucket [OPTIONS] COMMAND [ARGS]...

Your app's object storage bucket.

bucket status shows the bucket, its S3 endpoint and credentials, and how much of its limits it uses. The other commands work with its objects directly, from this machine. Mark the bucket's side of a path with a leading colon; : alone is the bucket's root:

freepod bucket ls -l :uploads
freepod bucket cp ./assets :public          upload a directory
freepod bucket cp :exports/report.csv .     download one object
freepod bucket link :exports/report.csv     a URL to share

Your running app already has the same credentials in its environment (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL, and S3_BUCKET).

freepod bucket cat

freepod bucket cat [OPTIONS] PATHS...

Write objects to stdout, exactly as stored.

Several objects are written one after another, in the order given.

freepod bucket cp

freepod bucket cp [OPTIONS] SOURCE DESTINATION

Copy files or objects between here and the bucket, or within it.

Mark the bucket's side with a leading colon; the marked side decides the direction. A directory or prefix is copied recursively, with no flag:

freepod bucket cp photo.jpg :images/       to images/photo.jpg
freepod bucket cp photo.jpg :cover.jpg     to exactly cover.jpg
freepod bucket cp ./site :public           a whole tree
freepod bucket cp :public ./backup         and back
freepod bucket cp :public :public-old      within the bucket

Existing files and objects are overwritten. Keys that would land outside the destination are skipped and reported.

freepod bucket link

freepod bucket link [OPTIONS] PATH

Print a presigned URL for one object.

Anyone holding the URL can download the object (or, with --put, upload to the key, as in curl -T file URL) until it expires, with no other credentials. The URL is the only output.

Option	Description
--put	a URL that uploads to the key, instead of downloading it
--expires DURATION	how long the URL works: a number with s, m, h or d; at most 7d [default: 1h]

freepod bucket ls

freepod bucket ls [OPTIONS] [PATH]

List a prefix of the bucket, or the root when no path is given.

Sub-prefixes are shown with a trailing /. The leading colon is optional: the path is always the bucket's.

Option	Description
-l	show each object's size and last-modified time
-r	list every object under the prefix, recursively

freepod bucket mv

freepod bucket mv [OPTIONS] SOURCE DESTINATION

Move files or objects: copy them, then delete each source.

Takes the same paths as cp. A source is deleted only after its copy has completed; one that could not be copied is kept and reported. Within the bucket, nothing is downloaded.

freepod bucket rm

freepod bucket rm [OPTIONS] PATHS...

Delete objects, or with -r everything under a prefix.

There is no undo: the bucket keeps no previous versions. The leading colon is optional; local files are never touched.

Option	Description
-r	delete everything under a prefix

freepod bucket status

freepod bucket status [OPTIONS]

Show this deployment's bucket, endpoint, credentials and usage.

The secret key is masked unless --show-secret is given.

Option	Description
--show-secret	print the secret key instead of masking it

freepod builds

freepod builds [OPTIONS]

List this project's builds, most recent first.

The build the deployment is currently running is marked with *. --verbose shows image references in full.

Option	Description
--limit N	how many builds to show (default: 20)
--all	show every build, ignoring --limit

freepod cp

freepod cp [OPTIONS] SOURCE DESTINATION

Copy a file or directory between here and this deployment.

Mark the deployment's side with a leading colon; the other side is local, and which one is marked decides the direction:

freepod cp report.csv :/app/report.csv     copy in
freepod cp :/app/out.log ./out.log         copy out
freepod cp ./assets :/app/assets           a whole tree, no flag needed

A relative remote path means what it means in freepod shell. Directories carry their structure and their files' modes; owners and timestamps are not preserved. Directories are always copied recursively. Nothing has to be installed in your image for this to work.

freepod db

freepod db [OPTIONS] COMMAND [ARGS]...

Your app's PostgreSQL database.

db status shows the database and role name, the password, and storage usage. db shell opens an interactive psql session. db proxy forwards a local port to the database and prints a connection URL for it.

Your running app already has the connection details in its environment (DATABASE_URL, PG*). The database is not reachable from this machine directly; db shell and db proxy connect over SSH.

freepod db proxy

freepod db proxy [OPTIONS]

Forward a local port to the database and print a connection URL.

The tunnel runs in the foreground until you press Ctrl+C. The URL points at the local end of the tunnel, so any client on this machine can use it. It is the only output on stdout.

Option	Description
--port PORT	the local port to listen on (default: 5432, or a free port if that one is in use)

freepod db shell

freepod db shell [OPTIONS]

Open an interactive psql session in this deployment's database.

psql runs on the platform, so no PostgreSQL client is needed on this machine, and the session works even when your app is down. Exits with psql's exit code.

freepod db status

freepod db status [OPTIONS]

Show this deployment's database, role, password and storage usage.

The password is masked unless --show-password is given.

Option	Description
--show-password	print the password instead of masking it

freepod delete

freepod delete [OPTIONS]

Delete this project's deployment and everything it stores.

Asks for confirmation first, then waits until the deletion has finished; the hostname cannot be reused before then.

.freepod.json keeps its settings, so a later freepod deploy creates a new deployment under the same hostname.

Option	Description
-y, --yes	skip the confirmation prompt (required when not run from a terminal)
--no-wait	return once the deletion has started instead of waiting for it to finish

freepod deploy

freepod deploy [OPTIONS]

Build the current project and release it to its deployment.

Uploads the project directory, builds an image from it and releases it. The first deploy also creates the deployment, which shows a placeholder page until the first build is live. Settings are checked before anything is uploaded, so most mistakes are reported in seconds rather than after a build.

The live address is the only output on stdout; build output and progress go to stderr, so URL=$(freepod deploy) captures the address.

Option	Description
--recreate	create a new deployment instead of updating the current one, which keeps running
--no-gitignore	also upload files that .gitignore excludes
--no-build	redeploy the current image without building, e.g. to apply staged vars

freepod init

freepod init [OPTIONS]

Set up the current directory as a Freepod project.

Asks for the project's settings, such as its hostname, and writes them to .freepod.json, which is meant to be committed. Nothing is deployed until you run freepod deploy.

Option	Description
--force	overwrite an existing .freepod.json; its deployment keeps running but is no longer linked to this project

freepod key

freepod key [OPTIONS] COMMAND [ARGS]...

Register the SSH public keys that identify you to the platform.

shell, cp, db shell and db proxy connect over SSH and need a registered key. A key belongs to your account and works for every deployment you own. Removing a key revokes its access.

Registering a key also makes it the one this machine uses, so connections offer exactly that key.

freepod key add

freepod key add [OPTIONS] [PATH]

Register a public key, generating one if no PATH is given.

With no PATH, generates an Ed25519 key in freepod's configuration directory (not ~/.ssh) and registers it. With a PATH, registers that public key file. Either way, the key becomes the one this machine uses.

Naming a key that is already registered makes it this machine's key without registering it again.

Option	Description
--label TEXT	the name key list shows (default: the key's comment)

freepod key list

freepod key list [OPTIONS]

List the keys registered on your account.

The key this machine uses is marked with *.

freepod key rm

freepod key rm [OPTIONS] FINGERPRINT

Revoke a key by the fingerprint freepod key list shows.

Works for keys this machine does not hold, such as one on a lost laptop.

freepod log

freepod log [OPTIONS]

Print this project's application output.

Application output goes to stdout and freepod's own messages to stderr, so freepod log > app.log captures only your app's output.

With -f the stream stays open, including across redeploys.

Option	Description
-f, --follow	keep the stream open and print lines as they arrive
-n, --tail LINES	how many recent lines to show first (default: set by the platform)
-r, --release NUMBER	pin to one release by its number, including one that failed and was rolled back
-t, --timestamps	prefix each line with the time the platform recorded for it

freepod login

freepod login [OPTIONS]

Sign in to Freepod and store the credential on this machine.

Opens a browser when one is available; otherwise prints a URL to open on any device.

Option	Description
--loopback	sign in through a browser on this machine
--device	sign in by opening a URL on any device, for machines without a browser
--force	sign in again even if a stored credential is valid

freepod logout

freepod logout [OPTIONS]

Remove the stored credential from this machine.

The credential stays valid until it expires or is revoked from your account settings.

freepod releases

freepod releases [OPTIONS]

List this project's releases, most recent first.

A release is one rollout of the deployment: a new build, changed vars, or changed settings. The release currently running is marked with *, and its number is what freepod log -r takes. --verbose shows image references in full.

Option	Description
--limit N	how many releases to show (default: 20)
--all	show every release, ignoring --limit

freepod shell

freepod shell [OPTIONS] [COMMAND]...

Open a shell in the app's container, or run COMMAND in it.

With no COMMAND the session runs on your own terminal and stays until you leave it. This is the command for a deployment that is up but misbehaving — the container is reachable even when the app inside it is not.

With a COMMAND it runs there and exits, the way ssh host COMMAND does: the words are joined and interpreted by the container's own shell, so quote a pipeline as one argument to keep it whole. Its input and output are this terminal's, so freepod shell cat app.log > local.log works.

Either way the exit code is the remote side's, with one ambiguity ssh itself has: 255 is also what ssh reports for its own failures.

Option	Description
-t, --tty	allocate a terminal for COMMAND — for a full-screen program such as top or an editor, which needs one to draw

freepod skill

freepod skill [OPTIONS] COMMAND [ARGS]...

Install the deployment instructions for your coding agents.

The skill is a SKILL.md file that tells a coding agent what an app needs to run on Freepod and how to deploy it with this CLI. It ships with the CLI, so it always matches the installed version.

freepod skill install

freepod skill install [OPTIONS]

Install the skill where your coding agents will find it.

With no options, installs for every supported agent whose configuration directory exists on this machine. --agent and --all choose agents explicitly; --dest writes the file to an exact path.

Existing copies are replaced. Every other freepod command also keeps installed copies current and installs for newly detected agents, unless FREEPOD_NO_SKILL=1 is set. The installed paths are printed to stdout, one per line.

Option	Description
--agent NAME	install for this agent whether or not it is detected; repeatable
--all	install for every supported agent
--project	install into this directory's per-agent skill folders rather than the home directory
--dest PATH	write SKILL.md to this exact path instead, for an agent not listed

freepod skill show

freepod skill show [OPTIONS]

Print the packaged skill to stdout.

Use it for an agent install does not support, or to read the skill before installing it.

freepod var

freepod var [OPTIONS] COMMAND [ARGS]...

Manage your app's environment variables.

Setting or removing a var redeploys the app so the change takes effect; --stage saves the change for the next deploy instead.

A var set with --secret is write-only: it is listed with its value hidden, and no command can print it back.

freepod var get

freepod var get [OPTIONS] KEY

Print one var's value.

Fails for a secret var, whose value cannot be read back.

freepod var list

freepod var list [OPTIONS]

List this deployment's vars.

The --json output can be piped back into freepod var set -f -. Secrets appear without a value, and an entry without a value leaves that var unchanged.

Option	Description
--json	print the vars as JSON

freepod var rm

freepod var rm [OPTIONS] KEYS...

Remove vars and redeploy.

Removing a var that is not set succeeds and changes nothing.

Option	Description
--stage	save the removal without redeploying

freepod var set

freepod var set [OPTIONS] [ASSIGNMENTS]...

Set vars and redeploy so they take effect.

Accepts KEY=VALUE pairs, a bare KEY to be prompted for without echo, or -f FILE. Several vars in one command are applied in one redeploy.

--stage saves them without redeploying, which also works while a deploy is in progress. freepod deploy --no-build applies staged vars.

Option	Description
--secret	store these vars write-only
-f, --file FILE	read vars from FILE: KEY=VALUE lines, or JSON as printed by var list --json; '-' reads stdin
--stage	save the vars without redeploying

freepod whoami

freepod whoami [OPTIONS]

Show the account you are signed in as.