# Updating and troubleshooting

How free-pi-cli stays up to date, and fixes for the problems people hit most often.

## Updating

- **Running with npx.** `npx free-pi-cli` can reuse a copy npm has already cached. Run `npx free-pi-cli@latest` to make sure you get the newest version.
- **Installed globally.** The CLI checks for a newer version at startup. If one exists and the CLI was installed with `npm install -g`, it updates itself, and the new version applies on the next launch. You can also run `/update` in the agent, or `npm install -g free-pi-cli@latest` yourself.
- **Required updates.** If your version is below the minimum the server allows, the CLI tries to update and otherwise stops with: update with `npx free-pi-cli@latest`.
- **Turning off auto-update.** Set `FREEPI_NO_AUTO_UPDATE=1` for one run, or put `{"autoUpdate": false}` in `~/.free-pi/config.json`. You then see an "Update Available" notice in the header instead.
- **After an update.** The next start shows what changed once. `/whats-new` shows recent highlights at any time.

The startup version check is quiet when you are offline. A failed check never blocks the CLI from starting.

## Troubleshooting

### "free-pi-cli can't run on Node ..."

Your Node.js is too old. The agent needs Node 22.15 or newer (23.8 or newer on the Current line). Upgrade, for example with `nvm install 22`, and run `npx free-pi-cli` again.

### "first-run consent needs an interactive terminal"

You ran the CLI where stdin is not a terminal, such as a script or CI job. free-pi is an interactive terminal app, so run `npx free-pi-cli` in a normal terminal.

### Sign-in does not open a browser

Over SSH or in a container there is no browser to open. Copy the URL printed in the terminal into a browser on any machine, and enter the code shown.

### A session is stuck, or another session is running

The server allows one active CLI session per account. If an earlier session did not shut down cleanly, run `/close-other-session` in the agent. If you cannot start the agent at all, wait a few minutes for the old session to expire and try again.

### Requests fail with a rate-limit or allowance message

You have probably reached today's free allowance. Run `/usage` to check. See [Models and limits](/docs/models-and-limits) for what to do.

### I want to sign in again or switch GitHub accounts

Run `free-pi-cli logout`, then start the CLI again. You will be asked to consent and sign in.

### "unknown argument"

The CLI only accepts `logout`, `--version`, and `--help`, or no argument at all. See [Commands and flags](/docs/commands-and-flags).

### The agent says a tool is not permitted

Only the built-in tool list is allowed. See [Using the agent](/docs/using-the-agent).

## Getting help

Ask the agent: it has a built-in guide to free-pi. For account or legal questions, email legal@freepi.ai.