Updating and troubleshooting

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 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.

The agent says a tool is not permitted

Only the built-in tool list is allowed. See 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.