> ## Documentation Index
> Fetch the complete documentation index at: https://docs.px0.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install px0, point it at a coding agent CLI as its model backend, scaffold a store, and confirm everything is wired up.

px0 is a Python CLI distributed on PyPI and installed with pipx. It writes everything it knows into one directory you own, `~/.px0` by default.

## Prerequisites

* **Python 3.11 or newer.**
* **A coding agent CLI** that px0 uses as its model backend: `claude`, `gemini`, `pi`, or `opencode`. px0 reuses that CLI's own login, so pick whichever one you already sign into.
* **A [Composio](https://composio.dev) API key**, for workflows that reach other apps. You can skip this and add it later.

## Install

```bash theme={null}
curl -fsSL https://px0.ai/install.sh | sh
```

The installer bootstraps pipx if it is missing, installs px0 from PyPI, runs `px0 init`, and offers to install the scheduler daemon.

Four environment variables change what it does:

| Variable        | Effect                                                         |
| :-------------- | :------------------------------------------------------------- |
| `PX0_VERSION`   | Pin a version: `PX0_VERSION=0.1.2 sh install.sh`               |
| `PX0_CHANNEL`   | `beta` installs pre-releases (`pipx install --pip-args=--pre`) |
| `PX0_PREFIX`    | Directory for the `px0` binary (sets `PIPX_BIN_DIR`)           |
| `PX0_NO_DAEMON` | `true` skips the daemon offer entirely                         |

<Note>
  Piping into `sh` leaves no terminal on stdin, so the daemon prompt is skipped automatically. Run `px0 daemon install` yourself afterwards.
</Note>

### Install from a clone

```bash theme={null}
python -m venv venv
source venv/bin/activate
pip install -e '.[dev]'      # the dev extra adds pytest
pytest
```

## Initialize a store

```bash theme={null}
px0 init
```

This scaffolds `~/.px0` (or `$PX0_HOME` if set): `workflows/`, `guidelines/`, `brain/`, `output/`, `tools/`, plus `config.toml` and a set of starter guideline files you can read, edit, or delete like any other file. Nothing here is hidden or binary.

`init` also asks for your Composio API key, which is what px0 uses to reach Gmail, Slack, GitHub, Calendar, and every other toolkit. Pass it directly, or skip it and set it later:

```bash theme={null}
px0 init --composio-key <your-api-key>   # non-interactive
px0 config composio <your-api-key>       # or set it up afterwards
```

There is no prompt when stdin is not a terminal, so `px0 init` is safe in scripts and installers - it creates the store and tells you to run `px0 config composio` when you have a key.

That key is all the connection setup there is. Individual apps authorize themselves the first time a workflow needs one, so you never connect a service you turn out not to use. See [Connections](/tools/connections).

## Pick a model backend

By default the model backend is `claude -p`. If you use a different coding agent CLI, pass `--harness` at init time:

```bash theme={null}
px0 init --harness gemini     # or pi, or opencode
```

That picks the right non-interactive invocation for the CLI and writes it to `model.harness_cmd` in `config.toml`.

| Harness    | Invocation     | Authentication                                           |
| :--------- | :------------- | :------------------------------------------------------- |
| `claude`   | `claude -p`    | Run `claude` once (OAuth), or set `ANTHROPIC_API_KEY`    |
| `gemini`   | `gemini -p`    | Set `GEMINI_API_KEY`, or run `gemini` once               |
| `pi`       | `pi -p`        | Set the provider's API key env var, or pass `--api-key`  |
| `opencode` | `opencode run` | Run `opencode auth login`, or set a provider key env var |

To switch later, or to pick a specific model rather than just the harness:

```bash theme={null}
px0 config model
```

It lists the harnesses it knows about with their `PATH` status, takes a model name to select, and actually invokes the result before saving - so a typo'd model name or a missing API key is caught there instead of mid-workflow. px0 never asks for or stores a provider key itself; that stays with the harness CLI's own login.

<Tip>
  Any other command works too. Set `model.harness_cmd` in `config.toml` to a wrapper script or a pinned path, and px0 appends the prompt as the final argument.
</Tip>

## Confirm it is wired up

```bash theme={null}
px0 doctor
```

Every line should be a `✓`. `doctor` exits `0` when everything passes and `4` when any check fails, so it works in a health-check script. On a freshly initialized store you will see something like:

```
✓ credentials              mode 0o600
✓ versions                 manifest opens cleanly
✓ locks                    no lock file yet
✓ schema                   store schema 2, binary schema 2
✓ connections              0 connection(s) configured
✓ workflows                every workflow file parses
✓ unreferenced_guidelines  6 unreferenced file(s)
✓ update                   0.1.0 (no update check recorded yet)
✓ daemon                   not running
✓ harness                  harness responded
✓ index                    0 brain files, 0 indexed passages
✓ private_folder           nothing held back
```

The starter guidelines are reported as unreferenced because no workflow lists them yet - that is expected on a new store, not a fault. `harness  harness responded` means px0 actually invoked your coding agent CLI and got something back; if that line fails, fix it before anything else, because every workflow depends on it.

See [Troubleshooting](/reference/troubleshooting) for what each check means and how to clear a failure.

## Colour, animation, and pipes

On a terminal px0 uses colour sparingly (a failure, a value you can act on) and shows a spinner while something slow is happening. Pipe it anywhere and all of that disappears: no escape sequences, no spinner redraws, and status glyphs become `[OK]` / `[FAIL]` so output stays greppable.

```bash theme={null}
px0 doctor | grep FAIL          # plain automatically
px0 --no-color doctor           # plain on a terminal too
NO_COLOR=1 px0 doctor           # same, via the environment
FORCE_COLOR=1 px0 doctor | less -R   # keep colour through a pipe
```

`--json` implies plain output everywhere - machine-readable data is never decorated.

## Uninstall

```bash theme={null}
sh install.sh --uninstall
```

This tears down any installed scheduler (launchd plist or systemd service) and removes the px0 binary via pipx / pip. Your store directory (`~/.px0`) and all your workflows, guidelines, brain, and history are preserved.

To remove px0 and delete all your store data at the same time:

```bash theme={null}
px0 uninstall
```

Or without interactive confirmation:

```bash theme={null}
px0 uninstall --yes
```

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/get-started/quickstart">
    Get a real output end to end.
  </Card>

  <Card title="Core concepts" icon="diagram-project" href="/get-started/concepts">
    What lives in the store, and why.
  </Card>
</CardGroup>

Once you have a workflow or two, `px0 status` is the fastest way to check whether anything needs attention - the daemon, recent failures, and the install itself, in one screen with no network call. See [Status](/reference/status).