CLI commands
Install: npm install -g forkstage. Every command takes -C <path> to act on another folder, and --help.
Account
Section titled “Account”| 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 |
Stacks
Section titled “Stacks”| 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 |
Environments
Section titled “Environments”| 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.
Self-hosting
Section titled “Self-hosting”| Command | Does |
|---|---|
forkstage host [user@address] [--identity file] |
set or show your own host |
Drivers
Section titled “Drivers”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 |
Files on your machine
Section titled “Files on your machine”~/.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.
Exit codes
Section titled “Exit codes”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.