Contents

Pethost CLI

pethost puts a folder online with one command, and shows and changes what runs there: logs, requests, a shell, secrets, a domain, a rollback.

Install

curl -fsSL https://pethost.dev/install.sh | sh                 # macOS, Linux
irm https://pethost.dev/install.ps1 | iex                      # Windows, in PowerShell
go install github.com/pethost-dev/cli/cmd/pethost@latest       # anywhere with Go

The script downloads one program, checks it against the release's checksums and puts it in ~/.local/bin. It needs no sudo and changes nothing else. Later, pethost update replaces the program with the newest release.

You need a Pethost account with a plan: get a machine. If you have none yet, pethost deploy shows you where to choose one, and waits.

Put a folder online

cd my-app
pethost deploy

The first time, your browser opens the Pethost panel to sign you in. The command asks for the project's name, which becomes its address, sends the folder to your machine, which builds and starts it, and prints the address. Run it again to deploy a new version.

The folder needs a Dockerfile or a compose file. If it has neither, run the command anyway: for most projects pethost writes the Dockerfile itself.

The README goes through the common tasks, each with the command's real output, and the deploy guides take one framework each.

Flags of every command

  • --debug print each call to the API on stderr
  • --json print the API's own answer as JSON
  • -p, --project string the project to act on, by its id
  • -q, --quiet print the answer alone
  • -y, --yes answer yes to a question

pethost help <command> prints in the terminal what this page says of a command.

Deploy and look

pethost deploy

Put a folder online; again, a new version

pethost deploy [dir] [flags]

Put a folder online: this one, or the one named. The first time it asks for the project's name, which becomes its address; again, it deploys a new version.

The folder needs a Dockerfile or a compose file. Everything in it is sent but what a build makes again, and the machine builds and runs it.

Where the folder has neither, pethost writes the Dockerfile itself for a project of a kind it knows: the file's first comment says what it read that from. A project it does not know it offers to a coding agent on this computer (Claude Code, Codex, pi), once you chose one; PETHOST_AGENT names one for a run, and PETHOST_AGENT=none turns that off. A Dockerfile it wrote is yours once its first deploy has built and started: it is never written again. One that fails there is taken back, and you are told what failed.

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn
  • --private give a new project no public address

Examples

pethost deploy
pethost deploy ./api
pethost deploy -p recipes        in a script: nothing is asked
pethost deploy --private         no public address

pethost status

What runs: this folder's project, else the machine and every project

pethost status [flags]

Examples

pethost
pethost status -p recipes
pethost --json

pethost ls

The machine and every project on it

pethost ls [flags]

Examples

pethost ls
pethost ls --json

pethost why

What is wrong or slow: problems, failing paths, the log lines near them

pethost why [flags]

One screen from three facts the machine keeps: the project's problems, as the machine words them; the paths whose requests failed (answered 5xx) in the last 24 hours; and what the service wrote at that moment. It says what it saw, and never guesses a cause.

With --json it prints the three answers the screen is made from, one a line: the project (GetProject), the day's traffic and the day's failed requests (QueryHttpTraffic).

Examples

pethost why
pethost why -p recipes

pethost logs

Container output: follow it, search it, or read the build log

pethost logs [service] [flags]

What the project's containers wrote, every service's or one's: the newest 100 lines, or with --since every line from then on. -f goes on with each new line until Ctrl-C.

--deploy is the newest deploy's own log instead, the build's and the start's; with -f it follows a deploy that still runs to its end. A deploy that sent no files and succeeded, as a change of the address or a rollback, is passed over: the line under the log says which deploy it is.

Flags

  • --deploy the newest deploy's own log instead
  • -f, --follow go on printing new lines as they are written
  • --grep string only lines that contain this text, in any case
  • -n, --lines uint32 how many of the newest lines (100; with --since, every line)
  • --since string how far back to look: 30m, 1h, 2d, or a moment as 2026-10-07T14:00:00Z

Examples

pethost logs
pethost logs web -f
pethost logs --since 1h --grep error
pethost logs -n 500
pethost logs --deploy

pethost requests

HTTP traffic: totals, busiest paths, the latest requests

pethost requests [flags]

The requests that reached the project's addresses: how many in the last 24 hours and how many of them failed (answered 5xx), the busiest paths, and the latest requests, one a line: when it finished, its status, what was asked, how long it took, the service that answered and who asked. -f shows only the requests, and goes on with each new one until Ctrl-C.

Flags

  • -f, --follow go on printing new requests as they finish
  • --path string only paths that contain this text
  • --since string how far back to look: 30m, 1h, 2d, or a moment as 2026-10-07T14:00:00Z (24h)
  • --status string only one class of status, 5xx, or one status, 404

Examples

pethost requests
pethost requests -f
pethost requests --status 5xx
pethost requests --path /api --since 1h

pethost open

Open the site in the browser

pethost open [service] [flags]

Opens the project's address in your browser, and prints it. A project whose services have addresses of their own opens the one of the service you name. Where there is no browser or no terminal, the address is only printed.

Examples

pethost open
pethost open api
pethost open -p recipes

Reach into a container

pethost run

Run one command in a container: its output, its exit code

pethost run [service] -- <command> [flags]

Runs one command in a service's running container and waits for its end.

The command's output goes to stdout and stderr as the command wrote it, and pethost exits as the command did: 124 when the machine stopped it at its timeout, 125 when pethost itself failed and the command's end is not known. The machine keeps the end of long output; for a program that talks back, or all of a long output, use pethost shell.

Flags

  • -u, --run-as-user string run it as this user, not the container's; "root" can install packages
  • -i, --stdin give it what is piped in as its stdin
  • --timeout-seconds uint32 stop it after this long, not after the machine's usual time
  • -w, --working-directory string run it in this directory, not the container's

Examples

pethost run -- ls /app
pethost run db -- psql -U postgres -c 'select count(*) from recipes'
pethost run web -- sh -c 'env | sort'
pethost run db -i -- psql -U postgres < seed.sql

pethost shell

Open a shell in a container

pethost shell [service] [flags]

Opens a shell in a service's running container, over SSH, with nothing to install.

On a terminal it is the container's own terminal: keys, colours, full-screen programs and the window's size all pass through. With commands piped in, it runs them and exits as the last one did. pethost exits as the shell did, and 255 when the connection broke.

The first use adds this computer's key to your machine: pethost machine lists the keys.

Examples

pethost shell
pethost shell db
echo 'ls -la /data' | pethost shell web

pethost tunnel

Bring a service's port to localhost, as a database to your laptop

pethost tunnel [service[:port]] [flags]

Opens a port on this computer that leads to a service's port in its container, over SSH.

Only this computer reaches it: it listens on localhost alone. The local port is the service's own, or the next free one, which the first line says; --local picks it. Without a port the service's only one is taken. Ctrl-C closes the tunnel.

Flags

  • --local uint16 the port on this computer, not the service's own

Examples

pethost tunnel db
pethost tunnel db:5432
pethost tunnel db --local 15432

pethost files

List a directory or print a file: the project's, a container's, a volume's

pethost files [name:]<path> [flags]

Lists a directory or prints a file on your machine.

A bare path is one of the project's own files, as they were deployed. With a name before it, the path is in that service's container, or in the volume of that name:

/compose.yaml     the project's file
web:/app          a directory in the container of the service web
data:/            the root of the volume data

A file that is not text is not written to a terminal: pethost cp copies it.

Flags

  • --service the name is a service's, where a volume has the same
  • --volume the name is a volume's, where a service has the same

Examples

pethost files /compose.yaml
pethost files web:/app
pethost files data:/
pethost files web:/app/config.json > config.json

pethost cp

Copy a file in or out of a container or a volume

pethost cp <from> <to> [flags]

Copies one file between this computer and your machine, straight to the machine.

One side is a path here; the other is on the machine, as pethost files writes it: a name and a colon before the path, a service's for its container or a volume's for that volume, and a colon alone for the project's own files, which can only be copied out.

A directory is copied out as a tar archive. A "-" in place of the local path is stdin or stdout. A file copied in takes the place of one already there; a destination that is a directory, here or there, takes the file under its own name.

Flags

  • --service the name is a service's, where a volume has the same
  • --volume the name is a volume's, where a service has the same

Examples

pethost cp web:/data/x.db ./x.db
pethost cp ./seed.sql db:/tmp/seed.sql
pethost cp data:/uploads ./uploads.tar
pethost cp :/compose.yaml .
pg_dump mydb | pethost cp - db:/tmp/dump.sql

Change a project

pethost env

The project's variables, names only

pethost env [flags]

The variables of the project's /.env file, names only, each with the services that read it. The file carries over from version to version: a deploy does not replace it.

pethost env --show     prints the file itself, with its values
pethost env set KEY    asks for the value without showing it

Commands

  • env set Set variables; a bare KEY reads its value hidden, or from stdin
  • env rm Remove variables
  • env push Replace the project's /.env with this folder's .env, or with a file

Flags

  • --show print the file itself, with its values

Examples

pethost env
pethost env set STRIPE_KEY
pethost env set PORT=3000 DEBUG=1
pethost env rm DEBUG
pethost env push
pethost env --show > .env

pethost env set

Set variables; a bare KEY reads its value hidden, or from stdin

pethost env set KEY[=VALUE]... [flags]

Set variables in the project's /.env and deploy it.

KEY alone asks for the value without showing it, so that it stays out of the shell's history; where nobody can be asked, the value is all of stdin. KEY=VALUE takes the value as typed. Either way the service gets exactly that value: the CLI quotes it in the file where the file needs it.

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost env set STRIPE_KEY
pethost env set PORT=3000 DEBUG=1
pethost env set STRIPE_KEY < key.txt
pethost env set DEBUG=          an empty value

pethost env rm

Remove variables

pethost env rm KEY... [flags]

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost env rm DEBUG
pethost env rm DEBUG OLD_FLAG

pethost env push

Replace the project's /.env with this folder's .env, or with a file

pethost env push [file] [flags]

Replace the project's /.env with this folder's .env, or with the file named, and deploy it. It names the variables that would disappear and asks first: a deploy never sends .env by itself once the project exists, and a rollback does not bring an earlier /.env back.

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost env push
pethost env push .env.production
pethost env push --yes -p recipes     in a script: nothing is asked

pethost domain

The project's addresses and their certificates

pethost domain [flags]

The project's addresses: where each leads, and how its certificate stands.

A name under your Pethost domain works at once over HTTPS. A domain of your own needs one DNS record, which "pethost domain add" prints; its certificate then comes by itself.

Commands

Examples

pethost domain
pethost domain add recipes.example.com
pethost domain add api.example.com api:8000
pethost domain rm recipes.example.com

pethost domain add

Give the project an address

pethost domain add <host> [service:port] [flags]

Give the project an address. Without service:port it leads where the project's addresses already lead, or to the one port a service listens on.

A name under your Pethost domain works at once. For a domain of your own the command prints the one DNS record to make; the certificate then comes by itself.

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost domain add recipes.example.com
pethost domain add api.example.com api:8000

pethost domain rm

Take an address away

pethost domain rm <host> [flags]

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost domain rm recipes.example.com

pethost password

Put a password page in front of the site, or take it away

pethost password [off] [flags]

Put a password page in front of every address of the project: visitors enter the password once. It is asked for without being shown, or read from stdin where nobody can be asked, and nothing ever prints it.

pethost password off     takes the page away: the site is public again

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost password
pethost password < password.txt
pethost password off

pethost rename

Change the name people see

pethost rename <name> [flags]

Change the name people see in the panel and in lists. The project's id, which is its address and what -p takes, never changes. An empty name removes it: people then see the id.

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost rename 'Recipe Box'
pethost rename ''                 no name: people see the id

pethost rollback

Go back to the version before, or to one of --list

pethost rollback [version] [flags]

Deploy the project's files as an earlier version had them: the version before, or the one named, by its id in "pethost rollback --list". The machine keeps the files of the three versions before the current one. A project that deploys from GitHub goes back to a commit, and stops following its branch until told to.

/.env, the addresses and the volumes' data are not part of a version: they stay.

Flags

  • --list list the versions to go back to
  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost rollback
pethost rollback --list
pethost rollback k3v9x2m1qa

pethost restart

Restart the project's services, or some of them

pethost restart [service...] [flags]

Restart the project's running services, or the ones named: the same containers, their processes started again.

--pull   gives each a new container instead, on the newest image of its tag, or
         built again on the newest base images. What a container wrote outside
         its volumes is then gone.

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn
  • --pull start again on the image's newest version, in a new container

Examples

pethost restart
pethost restart web
pethost restart web --pull

pethost stop

Stop the project's services, or some of them

pethost stop [service...] [flags]

Stop the project's services, or the ones named, each with its grace period. They stay stopped until "pethost start" or the next deploy; a restart of the machine may start them, as their restart policies say.

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost stop
pethost stop worker

pethost start

Start the project's stopped services, or some of them

pethost start [service...] [flags]

Start the project's stopped services and run its jobs again, or only the ones named. A service that has no container yet is started by a deploy.

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost start
pethost start worker

pethost backup

The project's snapshots

pethost backup [flags]

The project's snapshots: backups of its files and volumes, kept off the machine, taken every night and on demand while the machine's backups are on.

A project that was deleted keeps its snapshots: "pethost backup -p <id>" shows them, and "pethost backup restore <snapshot> -p <id>" brings the project back.

Commands

Examples

pethost backup
pethost backup now
pethost backup restore 3f9a1c2e

pethost backup now

Back the project up now

pethost backup now [flags]

Back up the project's files and volumes now, while it runs. It prints the snapshot's id.

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost backup now

pethost backup restore

Put a snapshot's data back

pethost backup restore <id> [flags]

Put a snapshot's data back. Of a project that is on the machine it replaces the volumes the snapshot holds, or the ones named with --volume: the project is backed up first, stopped, restored and started again, and its files stay as they are.

A deleted project comes back whole, files, volumes and source, and is deployed: name it with -p.

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn
  • --volume name a volume to replace, by its name; all the snapshot holds without it

Examples

pethost backup restore 3f9a1c2e
pethost backup restore 3f9a1c2e --volume data
pethost backup restore 3f9a1c2e -p recipes --yes

pethost volume

The project's volumes

pethost volume [flags]

The project's volumes: its lasting data. A volume survives deploys, and also its removal from compose.yaml: it then keeps its data, mounted by nothing, until "pethost volume rm" deletes it.

Commands

  • volume rm Delete a volume the project no longer declares

Examples

pethost volume
pethost volume rm old-data

pethost volume rm

Delete a volume the project no longer declares

pethost volume rm <name> [flags]

Delete a volume that compose.yaml no longer declares, with its data. The data then lives only in the snapshots that hold it. A volume still declared is refused: remove it from compose.yaml and deploy first.

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost volume rm old-data
pethost volume rm old-data --yes -p recipes

pethost github

Deploy from a GitHub repository: list them, connect one, or stop

pethost github [owner/repo] [flags]

Bare, it lists the repositories Pethost can deploy from: those your installation of its GitHub App covers. With a repository, the project takes its files from it from now on: every push to the branch deploys itself, and the same command turns that back on after a rollback. "pethost github off" goes back to the files as they are, which "pethost deploy" then replaces.

Commands

  • github off Stop deploying from GitHub: the files stay as they are

Flags

  • --branch string the branch to follow; the default one without it
  • --directory string the project's directory in it; the root without it
  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost github
pethost github sam/recipes
pethost github sam/recipes --branch main --directory apps/web
pethost github off

pethost github off

Stop deploying from GitHub: the files stay as they are

pethost github off [flags]

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn

Examples

pethost github off

pethost delete

Delete the project

pethost delete [flags]

Delete the project: its containers, volumes, files, addresses and logs.

While the machine's backups are on, a final backup is taken first and the project's snapshots stay: "pethost backup restore" brings it back. While they are off, it is gone for good.

It asks you to type the project's id. Where nobody can be asked, name the project with -p and say --yes.

--skip-final-backup   deletes without the final backup: what changed since the
                      newest snapshot is lost

Flags

  • --no-queue fail when the project is busy instead of waiting for its turn
  • --skip-final-backup take no final backup first

Examples

pethost delete
pethost delete -p recipes --yes

The machine, and this program

pethost machine

The machine: its resources, SSH keys and open sessions

pethost machine [flags]

The machine your projects run on: its plan and resources, where its disk goes, its backups, the SSH keys that open its containers and the sessions open in them now. The plan itself is changed in the panel.

Commands

Examples

pethost machine
pethost machine restart
pethost machine restart --at 03:00
pethost machine keys rm SHA256:Yx3…
pethost machine sessions end k3f9

pethost machine restart

Restart the machine, now or at a time

pethost machine restart [flags]

Restart the machine: now, or at a time. Every project is down while it restarts, and containers come back as their restart policies say. It waits for operations and backups that run to end first.

--at 03:00               the next time the clock here says so
--at "2026-10-08 03:00"  that moment; an RFC 3339 time is read too
--at night               the machine's next nightly window
--cancel                 no restart after all

Flags

  • --at string when to restart instead of now: a time, or night
  • --cancel cancel the restart that is scheduled

Examples

pethost machine restart
pethost machine restart --at 03:00
pethost machine restart --at night
pethost machine restart --cancel

pethost machine keys

The SSH keys that open the containers

pethost machine keys [flags]

Your public keys on the machine: each opens a shell, SFTP and tunnels into every container of every project. "pethost shell" adds this computer's key by itself.

Commands

Examples

pethost machine keys
pethost machine keys rm SHA256:Yx3…

pethost machine keys rm

Remove an SSH key; its sessions end

pethost machine keys rm <fingerprint> [flags]

Remove a key from the machine: the sessions it opened end, and it opens no more. Name it by its fingerprint, by the fingerprint's start, or by its label.

Examples

pethost machine keys rm SHA256:Yx3…
pethost machine keys rm 'MacBook Pro'

pethost machine sessions

What is open in the containers now

pethost machine sessions [flags]

What people have open in the containers now: shells, commands, file transfers, tunnels and the panel's terminals, oldest first.

Commands

Examples

pethost machine sessions
pethost machine sessions end k3f9

pethost machine sessions end

End a session

pethost machine sessions end <id> [flags]

End a session now. Its key can open new ones: "pethost machine keys rm" takes the key away.

Examples

pethost machine sessions end k3f9

pethost login

Sign in, in the browser

pethost login [flags]

Sign in: your browser opens the panel, where you press Connect. The sign-in is kept on this computer, in a file only you can read, until pethost logout.

Where no browser can open, as in a remote shell, sign in with an API token: make one in the panel's Settings, under API tokens, and give it to pethost login --token on stdin. A program needs neither: it reads PETHOST_TOKEN.

Flags

  • --token read an API token from stdin, for a shell with no browser

Examples

pethost login
pethost login --token < token.txt

pethost logout

Forget this computer's sign-in

pethost logout [flags]

Forget this computer's sign-in. Nothing on your machine changes: your projects go on running.

Examples

pethost logout

pethost whoami

Who is signed in, and where

pethost whoami [flags]

Which account's machine the commands act on: its plan and its domain, the panel they call, and whether they are signed in by PETHOST_TOKEN or by this computer's own sign-in. The token itself is never printed.

Examples

pethost whoami

pethost update

Replace this program with the newest release

pethost update [flags]

Replace this program with the newest release: its binary is downloaded, checked against the release's checksums and put in this one's place. A program that came by go install is told the go install line to run instead.

pethost says by itself when a newer release is out: once a day at most, on a terminal only, after a command's own output. PETHOST_NO_UPDATE_CHECK=1 turns that off.

Examples

pethost update

pethost completion

Print a shell's completions: bash, zsh, fish or powershell

pethost completion [flags]

Print the completions of your shell. They complete commands and flags, and the names of your projects and services, which they ask your machine for.

Commands

Examples

pethost completion zsh > "${fpath[1]}/_pethost"
pethost completion fish > ~/.config/fish/completions/pethost.fish
echo 'source <(pethost completion bash)' >> ~/.bashrc
pethost completion powershell >> $PROFILE

pethost completion bash

The completions of bash

pethost completion bash

Print bash's completions. A line in ~/.bashrc loads them into every new shell. bash needs the bash-completion package.

Flags

  • --no-descriptions disable completion descriptions

Examples

echo 'source <(pethost completion bash)' >> ~/.bashrc
source <(pethost completion bash)         this shell only

pethost completion zsh

The completions of zsh

pethost completion zsh [flags]

Print zsh's completions. Written once into a folder of zsh's fpath, they are there in every new shell. zsh needs its completion system on: autoload -U compinit; compinit in ~/.zshrc.

Flags

  • --no-descriptions disable completion descriptions

Examples

pethost completion zsh > "${fpath[1]}/_pethost"
source <(pethost completion zsh)          this shell only

pethost completion fish

The completions of fish

pethost completion fish [flags]

Print fish's completions. Written once into fish's completions folder, they are there in every new shell.

Flags

  • --no-descriptions disable completion descriptions

Examples

pethost completion fish > ~/.config/fish/completions/pethost.fish
pethost completion fish | source          this shell only

pethost completion powershell

The completions of powershell

pethost completion powershell [flags]

Print PowerShell's completions. Added once to your profile ($PROFILE), they are there in every new session.

Flags

  • --no-descriptions disable completion descriptions

Examples

pethost completion powershell >> $PROFILE
pethost completion powershell | Out-String | Invoke-Expression          this session only

pethost api

Call any API method, raw

pethost api [Method] [json] [flags]

Call a method of the API by its name, and print its answer as the API's JSON.

The request is the API's JSON too: the argument after the method, or stdin when that argument is "-". Without one the request is empty. A field the API does not have is refused, never sent. A stream prints an answer a line until Ctrl-C.

Without a method, every method is listed. Their requests and answers: https://pethost.dev/docs/api/

Examples

pethost api
pethost api GetMachine
pethost api GetProject '{"project_id": "recipes"}'
pethost api DeployProject - < request.json
pethost api TailContainerLogs '{"project_id": "recipes"}'

pethost help

What pethost does, or how one command is used

pethost help [command] [flags]

Examples

pethost help
pethost help deploy
pethost help env set