> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pt-act/pi-mono/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get Pi running in minutes and start building with AI assistance

## Install Pi

Pi is distributed as an npm package and requires Node.js 20 or later.

<Steps>
  <Step title="Install Pi globally">
    ```bash theme={null}
    npm install -g @mariozechner/pi-coding-agent
    ```

    This makes the `pi` command available system-wide.
  </Step>

  <Step title="Set up authentication">
    Choose one of two authentication methods:

    <Tabs>
      <Tab title="API Key (Simple)">
        Set an environment variable for your preferred provider:

        ```bash theme={null}
        export ANTHROPIC_API_KEY=sk-ant-...
        ```

        <Tip>
          Add this to your `~/.bashrc` or `~/.zshrc` to make it permanent.
        </Tip>

        Supported providers:

        * `ANTHROPIC_API_KEY` - Anthropic
        * `OPENAI_API_KEY` - OpenAI
        * `GEMINI_API_KEY` - Google Gemini
        * `GROQ_API_KEY` - Groq
        * `MISTRAL_API_KEY` - Mistral
        * And [many more](/installation#api-key-providers)
      </Tab>

      <Tab title="Subscription (OAuth)">
        If you have a subscription to Claude Pro, ChatGPT Plus, or GitHub Copilot:

        ```bash theme={null}
        pi
        /login
        ```

        Then select your provider from the menu. Credentials are saved to `~/.pi/agent/auth.json` and auto-refresh.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Launch Pi">
    ```bash theme={null}
    pi
    ```

    You'll see the interactive terminal interface with an editor at the bottom.
  </Step>

  <Step title="Start coding">
    Type your request and press Enter:

    ```
    List all TypeScript files in this directory
    ```

    Pi will use the built-in tools (`read`, `write`, `edit`, `bash`) to fulfill your request.
  </Step>
</Steps>

## Your First Session

Let's walk through a typical Pi session:

<CodeGroup>
  ```bash Terminal theme={null}
  # Start Pi in your project directory
  cd ~/my-project
  pi

  # Pi loads and shows the interface
  # Type your first message:
  "Create a simple HTTP server in Node.js that responds with 'Hello World'"

  # Pi will:
  # 1. Create a new file (server.js)
  # 2. Write the code
  # 3. Show you what it did

  # Continue the conversation:
  "Add a /status endpoint that returns JSON"

  # Pi edits the existing file and shows the changes
  ```
</CodeGroup>

<Note>
  Sessions auto-save to `~/.pi/agent/sessions/` organized by working directory. Use `pi -c` to continue your most recent session.
</Note>

## Essential Commands

Type `/` in the editor to see all commands. Here are the most useful:

| Command     | Description                              |
| ----------- | ---------------------------------------- |
| `/model`    | Switch between LLM models                |
| `/settings` | Adjust thinking level, theme, and more   |
| `/tree`     | Navigate session history and branches    |
| `/copy`     | Copy last assistant message to clipboard |
| `/hotkeys`  | Show all keyboard shortcuts              |
| `/quit`     | Exit Pi                                  |

## Essential Keyboard Shortcuts

| Key                       | Action                                                             |
| ------------------------- | ------------------------------------------------------------------ |
| `Ctrl+L`                  | Open model selector                                                |
| `Ctrl+P` / `Shift+Ctrl+P` | Cycle through models                                               |
| `Shift+Tab`               | Cycle thinking level (off → minimal → low → medium → high → xhigh) |
| `Escape`                  | Cancel current operation                                           |
| `Escape` twice            | Open session tree view                                             |
| `Ctrl+C`                  | Clear editor (press twice to quit)                                 |
| `Ctrl+O`                  | Collapse/expand tool output                                        |
| `@`                       | Fuzzy-search and reference files                                   |

<Tip>
  Use `Shift+Enter` (or `Ctrl+Enter` on Windows Terminal) for multi-line input.
</Tip>

## File References

Include files in your messages using the `@` symbol:

```
@src/server.ts Review this file for security issues
```

Type `@` and start typing to get fuzzy-search suggestions. You can reference multiple files:

```
@package.json @README.md Update the dependencies and document the changes
```

## Running Bash Commands

Prefix commands with `!` to run them and send output to the LLM:

```bash theme={null}
!ls -la src/
```

Use `!!` to run without sending output:

```bash theme={null}
!!npm install lodash
```

## Session Management

<AccordionGroup>
  <Accordion title="Continue Previous Session" icon="play">
    ```bash theme={null}
    pi -c
    ```

    Resumes the most recent session for the current directory.
  </Accordion>

  <Accordion title="Browse All Sessions" icon="list">
    ```bash theme={null}
    pi -r
    ```

    Opens an interactive picker to select from past sessions.
  </Accordion>

  <Accordion title="Branch from History" icon="code-branch">
    Inside Pi, press `Escape` twice to open the session tree. Navigate to any point in history, then:

    * Press Enter to continue from that point
    * Type `/fork` to create a new session file from that branch
  </Accordion>

  <Accordion title="Export or Share" icon="share">
    ```
    /export my-session.html
    ```

    Creates a standalone HTML file with your session.

    ```
    /share
    ```

    Uploads your session as a private GitHub gist with a shareable HTML link.
  </Accordion>
</AccordionGroup>

## Switching Models

Pi supports 20+ LLM providers. Switch models at any time:

<Steps>
  <Step title="Open model selector">
    Press `Ctrl+L` or type `/model`
  </Step>

  <Step title="Choose your model">
    Use arrow keys and search to find your model. The list shows:

    * Model name and provider
    * Context window size
    * Pricing (input/output tokens)
    * Whether it supports vision and reasoning
  </Step>

  <Step title="Continue conversation">
    Your session continues with the new model. Pi handles cross-provider compatibility automatically.
  </Step>
</Steps>

<Note>
  Use `pi --models "claude-*,gpt-4o"` to limit `Ctrl+P` cycling to specific model patterns.
</Note>

## Next Steps

Now that you have Pi running, explore these key areas:

<CardGroup cols={2}>
  <Card title="Installation Details" icon="download" href="/installation">
    Platform-specific setup, API keys, and advanced configuration
  </Card>

  <Card title="Interactive Mode" icon="terminal" href="/guides/interactive-mode">
    Master the terminal UI, editor features, and message queue
  </Card>

  <Card title="Providers & Models" icon="cloud" href="/guides/providers-and-models">
    Set up multiple providers and understand model selection
  </Card>

  <Card title="Customization" icon="puzzle-piece" href="/guides/customization">
    Extend Pi with skills, extensions, and prompt templates
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pi command not found" icon="triangle-exclamation">
    After installing globally, you may need to restart your terminal or reload your shell:

    ```bash theme={null}
    source ~/.bashrc  # or ~/.zshrc
    ```

    If that doesn't work, check your npm global bin directory is in PATH:

    ```bash theme={null}
    npm config get prefix
    # Should output a path like /usr/local or ~/.npm-global
    ```
  </Accordion>

  <Accordion title="Authentication errors" icon="key">
    If you see authentication errors:

    1. Verify your API key is set correctly:
       ```bash theme={null}
       echo $ANTHROPIC_API_KEY
       ```

    2. Check the key format matches your provider's requirements

    3. For OAuth providers, try logging out and back in:
       ```bash theme={null}
       pi
       /logout
       /login
       ```
  </Accordion>

  <Accordion title="Windows: bash not found" icon="windows">
    Pi requires bash on Windows. Install [Git for Windows](https://git-scm.com/download/win) which includes Git Bash.

    See the [Windows setup guide](/installation#windows) for details.
  </Accordion>

  <Accordion title="Node.js version errors" icon="node">
    Pi requires Node.js 20 or later. Check your version:

    ```bash theme={null}
    node --version
    ```

    If needed, install a newer version from [nodejs.org](https://nodejs.org/) or use [nvm](https://github.com/nvm-sh/nvm):

    ```bash theme={null}
    nvm install 20
    nvm use 20
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  For more help, join the [Discord community](https://discord.com/invite/3cU7Bz4UPx) or check the [GitHub issues](https://github.com/badlogic/pi-mono/issues).
</Tip>