free-piView as Markdown All docs

Documentation

Getting started

Install and run the free-pi CLI, sign in with GitHub, and start your first coding session in the terminal.

What you need

  • A terminal.
  • Node.js 22.15 or newer. On the Current release line, 23.8 or newer works. Older Node versions crash inside the agent, so free-pi-cli checks for this at startup and stops with a message if your Node is too old. To upgrade with nvm, run nvm install 22.
  • A GitHub account.

Run it

npx free-pi-cli

You do not need to install anything first. npx downloads and runs the CLI. Use npx free-pi-cli@latest to make sure you get the newest version.

If you prefer a shorter command, install it once globally and run it by name:

npm install -g free-pi-cli
free-pi-cli

The command is free-pi-cli, not pi.

What happens on the first run

  1. Consent screen. free-pi shows a consent screen and asks Accept? [y/N]. It covers ads, training on your sessions, and the Terms of Service and Privacy Policy. If you decline, the CLI exits and nothing is sent to the free-pi server. See Ads and privacy for what the screen says.
  2. Welcome message. A short intro explains that ads keep free-pi free and that one CLI session per account runs at a time. Set FREEPI_NO_INTRO=1 to skip it.
  3. GitHub sign-in. The CLI prints a URL and a code, and tries to open the URL in your browser. Enter the code on that page and approve the sign-in. The CLI waits and continues once you finish. Over SSH or in a container, no browser opens, so copy the printed URL into a browser on another machine.
  4. The agent starts. The terminal switches to the coding agent. See Using the agent.

Consent needs an interactive terminal. If stdin is not a TTY (for example in a script or CI), the CLI explains this and exits. Run npx free-pi-cli once in a normal terminal to accept, and later runs work.

Running it again

Your sign-in token is saved, so closing the terminal does not sign you out. Run npx free-pi-cli again and you go straight into the agent. The token is checked at startup. If the server no longer accepts it, you are asked to consent and sign in again.

Where files are stored

free-pi keeps its configuration and sign-in token under ~/.free-pi/agent. This is separate from ~/.pi/agent, so an existing pi install is not touched.

Signing out

free-pi-cli logout

This deletes the stored sign-in token on your machine. The next run asks you to consent and sign in again.

Using the agent →