pre.dev CLI

The predev CLI reads and edits files in your working directory. It connects that directory to a pre.dev project for conversation history and planning artifacts.

Install and launchCopy Anchor Link

The installer supports macOS and Linux on ARM64 and x64. It requires curl and Python 3.

curl -fsSL https://pre.dev/install | bash

It installs under ~/.predev, adds predev to your shell path, and launches the CLI in an interactive terminal. For installation without launching:

curl -fsSL https://pre.dev/install | PREDEV_NO_AUTORUN=1 bash

Then run it from your repository:

cd my-project
predev

If your shell has not picked up the PATH change, open a new terminal or run ~/.predev/bin/predev.

First runCopy Anchor Link

Sign in through the browser when prompted, then return to the terminal. The CLI stores its credential in ~/.predev/auth.json; /login signs in again or switches accounts, and /logout signs this machine out.

The CLI resolves a project for the directory and resumes it on subsequent launches. A folder with code starts as a full project. A folder without code starts chat only: the agent and all its tools, with no keys, database, or file sync until you build something there or type /project. Use predev --new to create a fresh project association. An existing codebase can be mapped with /reverse before you request changes.

predev "add an empty state to the reports page"
predev open "https://pre.dev/projects/$PROJECT_ID"
predev --version
predev --help

predev open brings an existing project, for example one you started on the web, into the current folder: its files are pulled here and it runs on this machine. A chat-only project opens in the folder it last ran in.

Sign in without a browserCopy Anchor Link

Set PREDEV_API_KEY to your workspace API key and the CLI signs in with it when the computer has no saved login, as in CI, coding agents and fresh machines. A saved browser login always wins, so exporting the key for the AI Gateway does not change who you are in the CLI. To use the key on a computer with a saved login, run predev logout first. Copy the key from Integrations → Built-in in the dashboard (the AI card).

export PREDEV_API_KEY="pdk_..."
predev

The CLI checks the key with pre.dev when it starts and keeps it in memory only. It never writes the key to ~/.predev/auth.json. A rejected key stops the CLI with PREDEV_API_KEY was rejected (revoked or wrong key) and exit code 2; the CLI does not fall back to the browser.

Set the key in your shell or CI environment. The CLI never reads its own settings from a project’s .env file. The CLI says which identity it is using at startup (the email, never the key). /login works as usual, and the saved login it creates wins over the key.

Run one task without the appCopy Anchor Link

predev run sends one request to the agent in the current directory, prints the result, and exits. It works on the same project as predev in that directory, needs no browser, and never waits for input.

predev run "add a health check endpoint with a test"
echo "fix the failing test in src/date.test.ts" | predev run
predev run --new "scaffold a command-line tool in Go"

• With no prompt argument, predev run reads the prompt from stdin, to the end of input or until 10 seconds pass without input. --new before the prompt creates a fresh project for the directory.
• Standard output has one [predev] line per step, then the agent’s final message. Errors go to standard error.
• Before it exits, the command waits up to two minutes for the run’s edits to sync to pre.dev, and it stops processes the agent started, such as dev servers.
• The run takes the directory’s session for this computer, like predev does. Afterwards the session stays assigned to this computer and shows as offline on the web, as after quitting predev.
• The directory as it is on disk is the source of truth. predev run pulls the session’s files from pre.dev only into a directory that synced this session before, and never when the CI environment variable is set, so a CI checkout never picks up files that earlier runs created on other commits. Most CI services set CI for you. Jenkins, Azure Pipelines and AWS CodeBuild do not: set CI=true there, above all on agents that keep their home directory between jobs.
• In CI, the account email in the output is masked.
• Parallel jobs that share one checkout path use predev run --new, which gives each job its own project.
• If the directory’s session runs in the cloud or on another computer that is online, or a run is already in progress there, the command exits with code 1 and changes nothing. Open predev in the directory (type /local to bring a cloud session back), or use predev run --new. A session left on a computer that is offline moves to this one, so CI runners with a fresh home directory can run predev run every time.
• Ctrl-C stops the run. Press it again to quit at once.

To answer a question, run predev run "<your answer>" in the same directory. The conversation continues from there.

Work in the terminalCopy Anchor Link

The agent decides whether to answer, plan, or build. Use /sprint <feature> for a dedicated sprint and /fork <task> for a separate session. /kanban, /roadmap, and /arch open project views in the terminal. /usage shows what the project’s credits went on, and /publish puts the app at its permanent address.

Review file changes with git status and git diff. /undo puts the files back the way they were before your last message or sprint, and /redo brings the change back.

Your laptop or the cloudCopy Anchor Link

A session you start in the CLI runs on your machine. The web shows the same session, and a message typed there runs on your laptop while the CLI is connected. When the app’s dev server is running, the owner can see it live in the web Preview.

The launcher checks for updates in the background and verifies downloaded releases. A background update can take effect on a later launch; predev --version reports the installed version in use.