Documentation

Commands and flags

The command-line flags, subcommands, environment variables, and slash commands you use with free-pi-cli.

Command line

free-pi-cli [command]

free-pi-cli: Starts the coding agent. On the first run it shows the consent screen and GitHub sign-in.
free-pi-cli logout: Removes the stored sign-in token. The next run signs in again.
free-pi-cli --version or -v: Prints the CLI version.
free-pi-cli --help, -h, or help: Prints usage.

Any other argument prints the help text and exits with an error. This is deliberate: a mistyped command such as loguot does not quietly start a session that uses your allowance. --version, --help, and logout never contact the free-pi server.

You can run these with npx free-pi-cli ... instead of installing the CLI.

Environment variables

FREEPI_BASE_URL: Overrides the backend URL. The default is https://api.freepi.ai. Useful for pointing at a local dev server.
FREEPI_NO_AUTO_UPDATE: Set to any value to disable in-place self-update for this run.
FREEPI_NO_INTRO: Set to 1 or true to skip the first-run welcome message.
FREEPI_KEEP_ENV_PROVIDERS: Set to 1 to keep model providers from your own environment in the model picker. By default the picker shows only free-pi models.

To turn off self-update permanently, create ~/.free-pi/config.json containing {"autoUpdate": false}.

Slash commands

Type / in the agent to list commands. These are the free-pi commands. None of them uses a model turn, so they work even when you are out of usage.

/usage: Shows how much of today's free allowance you have used, as a percentage, plus token counts.
/support: Opens today's advertiser in your browser.
/close-other-session: Clears a stuck session so you can start a new one.
/update: Updates free-pi-cli to the latest version.
/whats-new: Shows the highlights of the three most recent releases.
/tos: Opens the Terms of Service in your browser.
/privacy-policy: Opens the Privacy Policy in your browser.

The agent also has its own built-in commands, such as /model, which are part of pi.

Command details

/usage prints your account tier, the percentage of today's free allowance used, and today's and lifetime token counts.
/support only opens the advertiser's link. It grants nothing, and until an ad has loaded it says "No advertiser loaded yet."
/close-other-session replies "Cleared your other session" if it released one, or "No other session was running."
/update runs npm install -g free-pi-cli@latest. If you started the CLI with npx, it tells you that you are already up to date. To get the newest version through npx, run npx free-pi-cli@latest.