@eminent337/aery 0.1.58 → 0.1.59
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/docs.json +133 -0
- package/docs/index.md +61 -0
- package/docs/providers.md +1 -1
- package/docs/quickstart.md +142 -0
- package/docs/usage.md +275 -0
- package/package.json +1 -1
package/docs/docs.json
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
{
|
|
2
|
+
"navigation": [
|
|
3
|
+
{
|
|
4
|
+
"title": "Start here",
|
|
5
|
+
"items": [
|
|
6
|
+
{
|
|
7
|
+
"title": "Overview",
|
|
8
|
+
"path": "index.md"
|
|
9
|
+
},
|
|
10
|
+
{
|
|
11
|
+
"title": "Quickstart",
|
|
12
|
+
"path": "quickstart.md"
|
|
13
|
+
},
|
|
14
|
+
{
|
|
15
|
+
"title": "Using Pi",
|
|
16
|
+
"path": "usage.md"
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"title": "Providers",
|
|
20
|
+
"path": "providers.md"
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
"title": "Settings",
|
|
24
|
+
"path": "settings.md"
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"title": "Keybindings",
|
|
28
|
+
"path": "keybindings.md"
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
"title": "Sessions",
|
|
32
|
+
"path": "session.md"
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
"title": "Session Tree",
|
|
36
|
+
"path": "tree.md"
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
"title": "Compaction",
|
|
40
|
+
"path": "compaction.md"
|
|
41
|
+
}
|
|
42
|
+
]
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
"title": "Customization",
|
|
46
|
+
"items": [
|
|
47
|
+
{
|
|
48
|
+
"title": "Extensions",
|
|
49
|
+
"path": "extensions.md"
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
"title": "Skills",
|
|
53
|
+
"path": "skills.md"
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
"title": "Prompt Templates",
|
|
57
|
+
"path": "prompt-templates.md"
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
"title": "Themes",
|
|
61
|
+
"path": "themes.md"
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
"title": "Pi Packages",
|
|
65
|
+
"path": "packages.md"
|
|
66
|
+
},
|
|
67
|
+
{
|
|
68
|
+
"title": "Custom Models",
|
|
69
|
+
"path": "models.md"
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
"title": "Custom Providers",
|
|
73
|
+
"path": "custom-provider.md"
|
|
74
|
+
}
|
|
75
|
+
]
|
|
76
|
+
},
|
|
77
|
+
{
|
|
78
|
+
"title": "Programmatic Usage",
|
|
79
|
+
"items": [
|
|
80
|
+
{
|
|
81
|
+
"title": "SDK",
|
|
82
|
+
"path": "sdk.md"
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
"title": "RPC Mode",
|
|
86
|
+
"path": "rpc.md"
|
|
87
|
+
},
|
|
88
|
+
{
|
|
89
|
+
"title": "JSON Event Stream Mode",
|
|
90
|
+
"path": "json.md"
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
"title": "TUI Components",
|
|
94
|
+
"path": "tui.md"
|
|
95
|
+
}
|
|
96
|
+
]
|
|
97
|
+
},
|
|
98
|
+
{
|
|
99
|
+
"title": "Platform Setup",
|
|
100
|
+
"items": [
|
|
101
|
+
{
|
|
102
|
+
"title": "Windows",
|
|
103
|
+
"path": "windows.md"
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
"title": "Termux on Android",
|
|
107
|
+
"path": "termux.md"
|
|
108
|
+
},
|
|
109
|
+
{
|
|
110
|
+
"title": "tmux",
|
|
111
|
+
"path": "tmux.md"
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
"title": "Terminal Setup",
|
|
115
|
+
"path": "terminal-setup.md"
|
|
116
|
+
},
|
|
117
|
+
{
|
|
118
|
+
"title": "Shell Aliases",
|
|
119
|
+
"path": "shell-aliases.md"
|
|
120
|
+
}
|
|
121
|
+
]
|
|
122
|
+
},
|
|
123
|
+
{
|
|
124
|
+
"title": "Development",
|
|
125
|
+
"items": [
|
|
126
|
+
{
|
|
127
|
+
"title": "Development",
|
|
128
|
+
"path": "development.md"
|
|
129
|
+
}
|
|
130
|
+
]
|
|
131
|
+
}
|
|
132
|
+
]
|
|
133
|
+
}
|
package/docs/index.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Pi Documentation
|
|
2
|
+
|
|
3
|
+
Pi is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and pi packages.
|
|
4
|
+
|
|
5
|
+
## Quick start
|
|
6
|
+
|
|
7
|
+
Install pi with npm:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install -g @eminent337/aery
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Then run it in a project directory:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
pi
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Authenticate with `/login` for subscription providers, or set an API key such as `ANTHROPIC_API_KEY` before starting pi.
|
|
20
|
+
|
|
21
|
+
For the full first-run flow, see [Quickstart](quickstart.md).
|
|
22
|
+
|
|
23
|
+
## Start here
|
|
24
|
+
|
|
25
|
+
- [Quickstart](quickstart.md) - install, authenticate, and run a first session.
|
|
26
|
+
- [Using Pi](usage.md) - interactive mode, slash commands, context files, and CLI reference.
|
|
27
|
+
- [Providers](providers.md) - subscription and API-key setup for built-in providers.
|
|
28
|
+
- [Settings](settings.md) - global and project settings.
|
|
29
|
+
- [Keybindings](keybindings.md) - default shortcuts and custom keybindings.
|
|
30
|
+
- [Sessions](session.md) - session storage format and session files.
|
|
31
|
+
- [Session tree](tree.md) - branching and navigating previous turns.
|
|
32
|
+
- [Compaction](compaction.md) - context compaction and branch summarization.
|
|
33
|
+
|
|
34
|
+
## Customization
|
|
35
|
+
|
|
36
|
+
- [Extensions](extensions.md) - TypeScript modules for tools, commands, events, and custom UI.
|
|
37
|
+
- [Skills](skills.md) - Agent Skills for reusable on-demand capabilities.
|
|
38
|
+
- [Prompt templates](prompt-templates.md) - reusable prompts that expand from slash commands.
|
|
39
|
+
- [Themes](themes.md) - built-in and custom terminal themes.
|
|
40
|
+
- [Pi packages](packages.md) - bundle and share extensions, skills, prompts, and themes.
|
|
41
|
+
- [Custom models](models.md) - add model entries for supported provider APIs.
|
|
42
|
+
- [Custom providers](custom-provider.md) - implement custom APIs and OAuth flows.
|
|
43
|
+
|
|
44
|
+
## Programmatic usage
|
|
45
|
+
|
|
46
|
+
- [SDK](sdk.md) - embed pi in Node.js applications.
|
|
47
|
+
- [RPC mode](rpc.md) - integrate over stdin/stdout JSONL.
|
|
48
|
+
- [JSON event stream mode](json.md) - print mode with structured events.
|
|
49
|
+
- [TUI components](tui.md) - build custom terminal UI for extensions.
|
|
50
|
+
|
|
51
|
+
## Platform setup
|
|
52
|
+
|
|
53
|
+
- [Windows](windows.md)
|
|
54
|
+
- [Termux on Android](termux.md)
|
|
55
|
+
- [tmux](tmux.md)
|
|
56
|
+
- [Terminal setup](terminal-setup.md)
|
|
57
|
+
- [Shell aliases](shell-aliases.md)
|
|
58
|
+
|
|
59
|
+
## Development
|
|
60
|
+
|
|
61
|
+
- [Development](development.md) - local setup, project structure, and debugging.
|
package/docs/providers.md
CHANGED
|
@@ -46,7 +46,7 @@ Use `/logout` to clear credentials. Tokens are stored in `~/.aery/agent/auth.jso
|
|
|
46
46
|
|
|
47
47
|
### Environment Variables or Auth File
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
Use `/login` in interactive mode and select a provider to store an API key in `auth.json`, or set credentials via environment variable:
|
|
50
50
|
|
|
51
51
|
```bash
|
|
52
52
|
export ANTHROPIC_API_KEY=sk-ant-...
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# Quickstart
|
|
2
|
+
|
|
3
|
+
This page gets you from install to a useful first pi session.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
Pi is distributed as an npm package:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install -g @eminent337/aery
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Then start pi in the project directory you want it to work on:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
cd /path/to/project
|
|
17
|
+
pi
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Authenticate
|
|
21
|
+
|
|
22
|
+
Pi can use subscription providers through `/login`, or API-key providers through environment variables or the auth file.
|
|
23
|
+
|
|
24
|
+
### Option 1: subscription login
|
|
25
|
+
|
|
26
|
+
Start pi and run:
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
/login
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Then select a provider. Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro (Codex), GitHub Copilot, Google Gemini CLI, and Google Antigravity.
|
|
33
|
+
|
|
34
|
+
### Option 2: API key
|
|
35
|
+
|
|
36
|
+
Set an API key before launching pi:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
40
|
+
pi
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
You can also run `/login` and select an API-key provider to store the key in `~/.aery/agent/auth.json`.
|
|
44
|
+
|
|
45
|
+
See [Providers](providers.md) for all supported providers, environment variables, and cloud-provider setup.
|
|
46
|
+
|
|
47
|
+
## First session
|
|
48
|
+
|
|
49
|
+
Once pi starts, type a request and press Enter:
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
Summarize this repository and tell me how to run its checks.
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
By default, pi gives the model four tools:
|
|
56
|
+
|
|
57
|
+
- `read` - read files
|
|
58
|
+
- `write` - create or overwrite files
|
|
59
|
+
- `edit` - patch files
|
|
60
|
+
- `bash` - run shell commands
|
|
61
|
+
|
|
62
|
+
Additional built-in read-only tools (`grep`, `find`, `ls`) are available through tool options. Pi runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback.
|
|
63
|
+
|
|
64
|
+
## Give pi project instructions
|
|
65
|
+
|
|
66
|
+
Pi loads context files at startup. Add an `AGENTS.md` file to tell it how to work in a project:
|
|
67
|
+
|
|
68
|
+
```markdown
|
|
69
|
+
# Project Instructions
|
|
70
|
+
|
|
71
|
+
- Run `npm run check` after code changes.
|
|
72
|
+
- Do not run production migrations locally.
|
|
73
|
+
- Keep responses concise.
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Pi loads:
|
|
77
|
+
|
|
78
|
+
- `~/.aery/agent/AGENTS.md` for global instructions
|
|
79
|
+
- `AGENTS.md` or `CLAUDE.md` from parent directories and the current directory
|
|
80
|
+
|
|
81
|
+
Restart pi, or run `/reload`, after changing context files.
|
|
82
|
+
|
|
83
|
+
## Common things to try
|
|
84
|
+
|
|
85
|
+
### Reference files
|
|
86
|
+
|
|
87
|
+
Type `@` in the editor to fuzzy-search files, or pass files on the command line:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
pi @README.md "Summarize this"
|
|
91
|
+
pi @src/app.ts @src/app.test.ts "Review these together"
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Images can be pasted with Ctrl+V (Alt+V on Windows) or dragged into supported terminals.
|
|
95
|
+
|
|
96
|
+
### Run shell commands
|
|
97
|
+
|
|
98
|
+
In interactive mode:
|
|
99
|
+
|
|
100
|
+
```text
|
|
101
|
+
!npm run lint
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
The command output is sent to the model. Use `!!command` to run a command without adding its output to the model context.
|
|
105
|
+
|
|
106
|
+
### Switch models
|
|
107
|
+
|
|
108
|
+
Use `/model` or Ctrl+L to choose a model. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.
|
|
109
|
+
|
|
110
|
+
### Continue later
|
|
111
|
+
|
|
112
|
+
Sessions are saved automatically:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
pi -c # Continue most recent session
|
|
116
|
+
pi -r # Browse previous sessions
|
|
117
|
+
pi --session <path|id> # Open a specific session
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Inside pi, use `/resume`, `/new`, `/tree`, `/fork`, and `/clone` to manage sessions.
|
|
121
|
+
|
|
122
|
+
### Non-interactive mode
|
|
123
|
+
|
|
124
|
+
For one-shot prompts:
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
pi -p "Summarize this codebase"
|
|
128
|
+
cat README.md | pi -p "Summarize this text"
|
|
129
|
+
pi -p @screenshot.png "What's in this image?"
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Use `--mode json` for JSON event output or `--mode rpc` for process integration.
|
|
133
|
+
|
|
134
|
+
## Next steps
|
|
135
|
+
|
|
136
|
+
- [Using Pi](usage.md) - interactive mode, slash commands, sessions, context files, and CLI reference.
|
|
137
|
+
- [Providers](providers.md) - authentication and model setup.
|
|
138
|
+
- [Settings](settings.md) - global and project configuration.
|
|
139
|
+
- [Keybindings](keybindings.md) - shortcuts and customization.
|
|
140
|
+
- [Pi Packages](packages.md) - install shared extensions, skills, prompts, and themes.
|
|
141
|
+
|
|
142
|
+
Platform notes: [Windows](windows.md), [Termux](termux.md), [tmux](tmux.md), [Terminal setup](terminal-setup.md), [Shell aliases](shell-aliases.md).
|
package/docs/usage.md
ADDED
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
# Using Pi
|
|
2
|
+
|
|
3
|
+
This page collects day-to-day usage details that do not fit on the quickstart page.
|
|
4
|
+
|
|
5
|
+
## Interactive Mode
|
|
6
|
+
|
|
7
|
+
<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
|
|
8
|
+
|
|
9
|
+
The interface has four main areas:
|
|
10
|
+
|
|
11
|
+
- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions
|
|
12
|
+
- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
|
|
13
|
+
- **Editor** - where you type; border color indicates the current thinking level
|
|
14
|
+
- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model
|
|
15
|
+
|
|
16
|
+
The editor can be replaced temporarily by built-in UI such as `/settings` or by custom extension UI.
|
|
17
|
+
|
|
18
|
+
### Editor Features
|
|
19
|
+
|
|
20
|
+
| Feature | How |
|
|
21
|
+
|---------|-----|
|
|
22
|
+
| File reference | Type `@` to fuzzy-search project files |
|
|
23
|
+
| Path completion | Press Tab to complete paths |
|
|
24
|
+
| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
|
|
25
|
+
| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
|
|
26
|
+
| Shell command | `!command` runs and sends output to the model |
|
|
27
|
+
| Hidden shell command | `!!command` runs without sending output to the model |
|
|
28
|
+
| External editor | Ctrl+G opens `$VISUAL` or `$EDITOR` |
|
|
29
|
+
|
|
30
|
+
See [Keybindings](keybindings.md) for all shortcuts and customization.
|
|
31
|
+
|
|
32
|
+
## Slash Commands
|
|
33
|
+
|
|
34
|
+
Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
|
|
35
|
+
|
|
36
|
+
| Command | Description |
|
|
37
|
+
|---------|-------------|
|
|
38
|
+
| `/login`, `/logout` | Manage OAuth or API-key credentials |
|
|
39
|
+
| `/model` | Switch models |
|
|
40
|
+
| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
|
|
41
|
+
| `/settings` | Thinking level, theme, message delivery, transport |
|
|
42
|
+
| `/resume` | Pick from previous sessions |
|
|
43
|
+
| `/new` | Start a new session |
|
|
44
|
+
| `/name <name>` | Set session display name |
|
|
45
|
+
| `/session` | Show session file, ID, messages, tokens, and cost |
|
|
46
|
+
| `/tree` | Jump to any point in the session and continue from there |
|
|
47
|
+
| `/fork` | Create a new session from a previous user message |
|
|
48
|
+
| `/clone` | Duplicate the current active branch into a new session |
|
|
49
|
+
| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
|
|
50
|
+
| `/copy` | Copy last assistant message to clipboard |
|
|
51
|
+
| `/export [file]` | Export session to HTML |
|
|
52
|
+
| `/share` | Upload as private GitHub gist with shareable HTML link |
|
|
53
|
+
| `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
|
|
54
|
+
| `/hotkeys` | Show all keyboard shortcuts |
|
|
55
|
+
| `/changelog` | Display version history |
|
|
56
|
+
| `/quit` | Quit pi |
|
|
57
|
+
|
|
58
|
+
## Message Queue
|
|
59
|
+
|
|
60
|
+
You can submit messages while the agent is still working:
|
|
61
|
+
|
|
62
|
+
- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
|
|
63
|
+
- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
|
|
64
|
+
- **Escape** aborts and restores queued messages to the editor.
|
|
65
|
+
- **Alt+Up** retrieves queued messages back to the editor.
|
|
66
|
+
|
|
67
|
+
On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want pi to receive the shortcut.
|
|
68
|
+
|
|
69
|
+
Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
|
|
70
|
+
|
|
71
|
+
## Sessions
|
|
72
|
+
|
|
73
|
+
Sessions are saved automatically to `~/.aery/agent/sessions/`, organized by working directory.
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pi -c # Continue most recent session
|
|
77
|
+
pi -r # Browse and select a session
|
|
78
|
+
pi --no-session # Ephemeral mode; do not save
|
|
79
|
+
pi --session <path|id> # Use a specific session file or session ID
|
|
80
|
+
pi --fork <path|id> # Fork a session into a new session file
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Useful session commands:
|
|
84
|
+
|
|
85
|
+
- `/session` shows the current session file and ID.
|
|
86
|
+
- `/tree` navigates the in-file session tree and can summarize abandoned branches.
|
|
87
|
+
- `/fork` creates a new session from an earlier user message.
|
|
88
|
+
- `/clone` duplicates the current active branch into a new session file.
|
|
89
|
+
- `/compact` summarizes older messages to free context.
|
|
90
|
+
|
|
91
|
+
See [Sessions](session.md), [Session Tree](tree.md), and [Compaction](compaction.md) for details.
|
|
92
|
+
|
|
93
|
+
## Context Files
|
|
94
|
+
|
|
95
|
+
Pi loads `AGENTS.md` or `CLAUDE.md` at startup from:
|
|
96
|
+
|
|
97
|
+
- `~/.aery/agent/AGENTS.md` for global instructions
|
|
98
|
+
- parent directories, walking up from the current working directory
|
|
99
|
+
- the current directory
|
|
100
|
+
|
|
101
|
+
Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
|
|
102
|
+
|
|
103
|
+
### System Prompt Files
|
|
104
|
+
|
|
105
|
+
Replace the default system prompt with:
|
|
106
|
+
|
|
107
|
+
- `.pi/SYSTEM.md` for a project
|
|
108
|
+
- `~/.aery/agent/SYSTEM.md` globally
|
|
109
|
+
|
|
110
|
+
Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
|
|
111
|
+
|
|
112
|
+
## Exporting and Sharing Sessions
|
|
113
|
+
|
|
114
|
+
Use `/export [file]` to write a session to HTML.
|
|
115
|
+
|
|
116
|
+
Use `/share` to upload a private GitHub gist with a shareable HTML link.
|
|
117
|
+
|
|
118
|
+
If you use pi for open source work and want to publish sessions for model, prompt, tool, and evaluation research, see [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). It publishes sessions to Hugging Face datasets.
|
|
119
|
+
|
|
120
|
+
## CLI Reference
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
pi [options] [@files...] [messages...]
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Package Commands
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
pi install <source> [-l] # Install package, -l for project-local
|
|
130
|
+
pi remove <source> [-l] # Remove package
|
|
131
|
+
pi uninstall <source> [-l] # Alias for remove
|
|
132
|
+
pi update [source|self|pi] # Update pi and packages; skips pinned packages
|
|
133
|
+
pi update --extensions # Update packages only
|
|
134
|
+
pi update --self # Update pi only
|
|
135
|
+
pi update --extension <src> # Update one package
|
|
136
|
+
pi list # List installed packages
|
|
137
|
+
pi config # Enable/disable package resources
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
See [Pi Packages](packages.md) for package sources and security notes.
|
|
141
|
+
|
|
142
|
+
### Modes
|
|
143
|
+
|
|
144
|
+
| Flag | Description |
|
|
145
|
+
|------|-------------|
|
|
146
|
+
| default | Interactive mode |
|
|
147
|
+
| `-p`, `--print` | Print response and exit |
|
|
148
|
+
| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
|
|
149
|
+
| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
|
|
150
|
+
| `--export <in> [out]` | Export a session to HTML |
|
|
151
|
+
|
|
152
|
+
In print mode, pi also reads piped stdin and merges it into the initial prompt:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
cat README.md | pi -p "Summarize this text"
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Model Options
|
|
159
|
+
|
|
160
|
+
| Option | Description |
|
|
161
|
+
|--------|-------------|
|
|
162
|
+
| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
|
|
163
|
+
| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
|
|
164
|
+
| `--api-key <key>` | API key, overriding environment variables |
|
|
165
|
+
| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
|
|
166
|
+
| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
|
|
167
|
+
| `--list-models [search]` | List available models |
|
|
168
|
+
|
|
169
|
+
### Session Options
|
|
170
|
+
|
|
171
|
+
| Option | Description |
|
|
172
|
+
|--------|-------------|
|
|
173
|
+
| `-c`, `--continue` | Continue the most recent session |
|
|
174
|
+
| `-r`, `--resume` | Browse and select a session |
|
|
175
|
+
| `--session <path\|id>` | Use a specific session file or partial UUID |
|
|
176
|
+
| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
|
|
177
|
+
| `--session-dir <dir>` | Custom session storage directory |
|
|
178
|
+
| `--no-session` | Ephemeral mode; do not save |
|
|
179
|
+
|
|
180
|
+
### Tool Options
|
|
181
|
+
|
|
182
|
+
| Option | Description |
|
|
183
|
+
|--------|-------------|
|
|
184
|
+
| `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
|
|
185
|
+
| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
|
|
186
|
+
| `--no-tools`, `-nt` | Disable all tools |
|
|
187
|
+
|
|
188
|
+
Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
|
|
189
|
+
|
|
190
|
+
### Resource Options
|
|
191
|
+
|
|
192
|
+
| Option | Description |
|
|
193
|
+
|--------|-------------|
|
|
194
|
+
| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
|
|
195
|
+
| `--no-extensions` | Disable extension discovery |
|
|
196
|
+
| `--skill <path>` | Load a skill; repeatable |
|
|
197
|
+
| `--no-skills` | Disable skill discovery |
|
|
198
|
+
| `--prompt-template <path>` | Load a prompt template; repeatable |
|
|
199
|
+
| `--no-prompt-templates` | Disable prompt template discovery |
|
|
200
|
+
| `--theme <path>` | Load a theme; repeatable |
|
|
201
|
+
| `--no-themes` | Disable theme discovery |
|
|
202
|
+
| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
|
|
203
|
+
|
|
204
|
+
Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
pi --no-extensions -e ./my-extension.ts
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### Other Options
|
|
211
|
+
|
|
212
|
+
| Option | Description |
|
|
213
|
+
|--------|-------------|
|
|
214
|
+
| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
|
|
215
|
+
| `--append-system-prompt <text>` | Append to system prompt |
|
|
216
|
+
| `--verbose` | Force verbose startup |
|
|
217
|
+
| `-h`, `--help` | Show help |
|
|
218
|
+
| `-v`, `--version` | Show version |
|
|
219
|
+
|
|
220
|
+
### File Arguments
|
|
221
|
+
|
|
222
|
+
Prefix files with `@` to include them in the message:
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
pi @prompt.md "Answer this"
|
|
226
|
+
pi -p @screenshot.png "What's in this image?"
|
|
227
|
+
pi @code.ts @test.ts "Review these files"
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Examples
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
# Interactive with initial prompt
|
|
234
|
+
pi "List all .ts files in src/"
|
|
235
|
+
|
|
236
|
+
# Non-interactive
|
|
237
|
+
pi -p "Summarize this codebase"
|
|
238
|
+
|
|
239
|
+
# Non-interactive with piped stdin
|
|
240
|
+
cat README.md | pi -p "Summarize this text"
|
|
241
|
+
|
|
242
|
+
# Different model
|
|
243
|
+
pi --provider openai --model gpt-4o "Help me refactor"
|
|
244
|
+
|
|
245
|
+
# Model with provider prefix
|
|
246
|
+
pi --model openai/gpt-4o "Help me refactor"
|
|
247
|
+
|
|
248
|
+
# Model with thinking level shorthand
|
|
249
|
+
pi --model sonnet:high "Solve this complex problem"
|
|
250
|
+
|
|
251
|
+
# Limit model cycling
|
|
252
|
+
pi --models "claude-*,gpt-4o"
|
|
253
|
+
|
|
254
|
+
# Read-only mode
|
|
255
|
+
pi --tools read,grep,find,ls -p "Review the code"
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### Environment Variables
|
|
259
|
+
|
|
260
|
+
| Variable | Description |
|
|
261
|
+
|----------|-------------|
|
|
262
|
+
| `PI_CODING_AGENT_DIR` | Override config directory; default is `~/.aery/agent` |
|
|
263
|
+
| `PI_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
|
|
264
|
+
| `PI_SKIP_VERSION_CHECK` | Skip version check at startup |
|
|
265
|
+
| `PI_TELEMETRY` | Override install telemetry: `1`/`true`/`yes` or `0`/`false`/`no` |
|
|
266
|
+
| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
|
|
267
|
+
| `VISUAL`, `EDITOR` | External editor for Ctrl+G |
|
|
268
|
+
|
|
269
|
+
## Design Principles
|
|
270
|
+
|
|
271
|
+
Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
|
|
272
|
+
|
|
273
|
+
It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
|
|
274
|
+
|
|
275
|
+
For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).
|