# 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](/docs/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](/docs/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.