Skip to content

CLI commands

Install: npm install -g forkstage. Every command takes -C <path> to act on another folder, and --help.

Command Does
forkstage login signs in with GitHub in the browser and stores a workspace token on this machine
forkstage login --token fst_… signs in with a token made in the dashboard (CI)
forkstage login --api <url> a different control plane
forkstage login --no-browser prints the sign-in address instead of opening it
forkstage logout forgets the sign-in on this machine (the token stays valid until revoked)
forkstage whoami the signed-in account and workspace
Command Does
forkstage init reads the repository and writes forkstage.yaml; --print shows it instead, --force overwrites
forkstage bake sends the repository and snapshots the running stack; --name <name> instead of the commit
forkstage snapshots the stack’s snapshots
Command Does
forkstage up forks the newest snapshot; prints the card. --driver cloud|firecracker|local
forkstage ls every fork this machine knows about, with state
forkstage status [id] the card plus each service’s state
forkstage sh [id] [-s service] an interactive shell inside a service
forkstage exec [id] [-s service] -- <command> one command inside a service; exit code is returned
forkstage logs [id] [-s service] [-n lines] recent logs
forkstage test [id] [--only name] the recipe’s test runs, recorded
forkstage proof [id] [--json] [--agent name] the proof as Markdown or JSON, also after the fork is gone
forkstage down [id] [--all] strikes the fork; keeps and publishes the proof
forkstage run [--keep] -- <command> fork, run the command with the fork in its environment, strike after

When [id] is omitted the latest fork started from the current folder is used.

Command Does
forkstage host [user@address] [--identity file] set or show your own host

cloud is the hosted service (default once signed in). firecracker is a host of your own over SSH (default when a host is set and you are not signed in). local is Docker on this machine (default otherwise). --driver on up, bake, snapshots and run overrides.

Environment variables the fork gives a command

Section titled “Environment variables the fork gives a command”

For forkstage run and inside forkstage exec’s context:

Variable Value
FORKSTAGE_URL the app’s address (public for cloud forks, 127.0.0.1:<port> for self-hosted and local)
FORKSTAGE_PUBLIC_URL the public address, when there is one
FORKSTAGE_<SERVICE>_URL each HTTP service’s address
DATABASE_URL, REDIS_URL for self-hosted and local forks, where ports are forwarded
FORKSTAGE_ENVIRONMENT the fork’s id
FORKSTAGE_CONTEXT one paragraph describing the fork, for agents

~/.forkstage/config.json (sign-in, host), ~/.forkstage/environments/<id>/ (live forks: record and timeline), ~/.forkstage/proofs/<id>/ (finished forks). Set FORKSTAGE_HOME to move them.

exec, test and run return the command’s exit code. Other commands return 0 on success and 1 on an error, with the reason and, where there is one, the fix on the next line.