sscoble/pi-mono
1
0
Fork 0
mirror of https://github.com/badlogic/pi-mono.git synced 2026-11-05 23:37:25 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

docs(coding-agent): refresh documentation (#9898)

Browse source 
* docs(coding-agent): improve getting started documentation

* docs(coding-agent): correct getting started details

* docs(coding-agent): clarify SDK entry point

* docs(coding-agent): restructure guides and references

* docs(coding-agent): improve getting started guides

* docs(coding-agent): refresh integration guides

* docs(coding-agent): improve terminal and CLI guides

* docs(coding-agent): refresh customisation guides

* docs(coding-agent): clarify project trust terminology

* docs(coding-agent): simplify customisation guidance

* docs(coding-agent): improve runtime and reference guidance

* Fix settings reference

* feat(coding-agent): add Crowdin documentation sync

* docs(coding-agent): separate CLI and slash command references

* docs(coding-agent): correct compaction reference

* docs(coding-agent): streamline package documentation

* docs(coding-agent): split RPC reference documentation

* Update configuration docs

* Shorten config docs

* docs(coding-agent): refine configuration references

* docs(coding-agent): streamline settings reference

* docs(coding-agent): clarify configuration reference

* docs(coding-agent): clarify project trust exception

* docs(coding-agent): simplify keybindings reference

* docs(coding-agent): remove Crowdin integration

* docs(coding-agent): turn themes reference into guide

* docs(coding-agent): consolidate model and authentication docs

* docs(tui): require Component.invalidate() (fixes #9358)

* docs(coding-agent): document offline catalog behavior (fixes #8684)

* docs(coding-agent): preserve established documentation routes

* docs(coding-agent): reorganize documentation navigation

* docs(coding-agent): correct audited behavior

Clarify provider, session, local-model, Termux, TUI, SDK, debug, and extension behavior. Simplify the documentation audit to report only clear user-visible contradictions.

* docs(coding-agent): fix broken documentation links
This commit is contained in:
Christian Klotz 2026-09-22 16:48:19 +02:00 • committed by GitHub
parent d201760ffe
commit 25cc5c7bf4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
49 changed files with 4187 additions and 11681 deletions
Download patch file Download diff file Expand all files Collapse all files

268
packages/coding-agent/docs/cli.md Normal file
View file

@ -0,0 +1,268 @@
<a id="cli-and-modes-reference"></a>
# Command Line
This page documents Pi's built-in command-line commands and options. Run `pi --help` or append `--help` to a command for the exact interface in your installed version. The top-level help also includes options registered by loaded extensions.
```sh
pi [options] [--] [@files...] [messages...]
pi install <source> [options]
pi remove <source> [options]
pi uninstall <source> [options]
pi update [target] [options]
pi list
pi config [options]
pi auth <check|print-api-key|print-bearer-token> [options]
```
<a id="modes"></a>
## Invocation and output
```sh
pi
pi --print "Summarize this repository"
git diff | pi --print "Review this change"
pi --mode json "Inspect this repository" > events.jsonl
```
With terminal stdin and stdout, Pi opens the terminal UI unless `--print`, `--mode json`, or `--mode rpc` selects another interface. When either stream is redirected and neither JSON nor RPC mode is selected, Pi uses print mode. See [CLI Integration](cli-integration.md) for choosing between interactive, print, JSON, RPC, and SDK integration.
| Input | Behavior |
|---|---|
| `message` | Provide an initial prompt |
| `@path` | Include a text file or image in the first prompt |
| Piped stdin | Prepend its contents to the first prompt |
| `--` | Stop option parsing so a prompt can begin with `-` |
Pi resolves `@path` from the current working directory. The working directory also controls project configuration, resource discovery, and session grouping.
`--print` controls whether Pi runs once and exits. `--mode` selects the output interface. `--mode text` does not force one-shot execution when stdin and stdout are terminals; use `--print` for that behavior.
| Option | Behavior |
|---|---|
| `-p`, `--print` | Run the supplied prompts, write the final assistant text to stdout, then exit |
| `--mode text` | Select text output; still open the terminal UI when stdin and stdout are terminals |
| `--mode json` | Run the supplied prompts, write JSONL events to stdout, then exit |
| `--mode rpc` | Read JSONL commands from stdin and write responses and events to stdout until shutdown |
| `--export <input> [output]` | Export a session file to HTML and exit; derive the destination when `output` is omitted |
RPC mode rejects `@file` arguments. JSON and RPC modes reserve stdout for protocol records. See [JSON Event Stream](json.md) and [RPC Protocol](rpc.md).
<a id="model-options"></a>
## Models
```sh
pi --model sonnet:high
```
See [Choose a Model](models.md) for model selection and [Provider Authentication](providers.md) for credentials.
- `--provider <name>`<br>
Restricts `--model` lookup to one provider.
- `--model <pattern>`<br>
Selects by exact ID or fuzzy ID/name match. It accepts `provider/id` and an optional `:<thinking>` suffix.
- `--api-key <key>`<br>
Uses a non-persistent API-key override. It requires a model selected through `--model` or `--models`.
- `--thinking <level>`<br>
Sets `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. It overrides a `--model` suffix and is clamped to the model's capabilities.
- `--models <patterns>`<br>
Sets a comma-separated scope for startup and cycling. It accepts exact IDs, fuzzy matches, case-insensitive globs, and optional `:<thinking>` suffixes.
- `--list-models [search]`<br>
Lists available models, optionally filtered by a fuzzy search, then exits.
<a id="session-options"></a>
## Sessions
```sh
pi --continue
```
See [Sessions and Context](sessions.md) for resuming, forking, naming, and storing sessions.
- `-c`, `--continue`<br>
Continues the most recent session for the current project.
- `-r`, `--resume`<br>
Opens the session selector.
- `--session <path|id>`<br>
Opens by file path, exact ID, or partial ID. Pi searches the current project first and offers to fork a cross-project match.
- `--session-id <id>`<br>
Opens the exact project session ID or creates it if absent. IDs accept letters, numbers, `.`, `_`, and `-`.
- `--fork <path|id>`<br>
Forks an existing session into a new session for the current project.
- `--session-dir <dir>`<br>
Overrides storage and lookup. It takes precedence over `PI_CODING_AGENT_SESSION_DIR` and the `sessionDir` setting.
- `--no-session`<br>
Uses an in-memory session that is not persisted.
- `-n`, `--name <name>`<br>
Sets the session display name.
Constraints:
- Session IDs must start and end with a letter or number.
- `--fork` cannot be combined with `--session`, `--continue`, `--resume`, or `--no-session`.
- `--session-id` cannot be combined with `--session`, `--continue`, or `--resume`. Combine it with `--fork` to choose the new ID.
<a id="tool-options"></a>
## Tools
```sh
pi --tools read,grep,find,ls --print "Review this project"
```
See [Settings](settings.md#tools) for configuring the default tool selection.
- `-t`, `--tools <list>`<br>
Replaces the default selection with a comma-separated allowlist of built-in, extension, or custom tools.
- `-xt`, `--exclude-tools <list>`<br>
Disables comma-separated tool names after all other selection options.
- `-nbt`, `--no-builtin-tools`<br>
Disables default built-in tools while retaining extension and custom tools.
- `-nt`, `--no-tools`<br>
Starts with all built-in, extension, and custom tools disabled.
Default enabled tools are `read`, `bash`, `edit`, and `write`, unless `defaultTools` changes them.
| Built-in | Purpose |
|---|---|
| `read` | Read text files and supported images |
| `bash` | Run shell commands |
| `powershell` | Run PowerShell commands on Windows |
| `edit` | Apply exact text replacements to an existing file |
| `write` | Create or overwrite a file |
| `grep` | Search file contents |
| `find` | Find paths using glob patterns |
| `ls` | List directory contents |
<a id="resource-options"></a>
## Resources
```sh
pi --extension ./review.ts
```
See [Configuration](configuration.md) for conventional directories and project trust, [Settings](settings.md#resources) for configured paths, and [Pi Packages](packages.md) for package sources.
- `-e`, `--extension <path>`<br>
Loads an extension file or directory and is repeatable.
- `-ne`, `--no-extensions`<br>
Disables discovered and configured extensions. Explicit `-e` paths still load.
- `--skill <path>`<br>
Loads a skill file or directory and is repeatable.
- `-ns`, `--no-skills`<br>
Disables discovered and configured skills. Explicit `--skill` paths still load.
- `--prompt-template <path>`<br>
Loads a prompt-template file or directory and is repeatable.
- `-np`, `--no-prompt-templates`<br>
Disables discovered and configured templates. Explicit `--prompt-template` paths still load.
- `--theme <path>`<br>
Loads a theme file or directory and is repeatable.
- `--use-theme <name[/name]>`<br>
Selects the initial interactive theme for this run.
- `--no-themes`<br>
Disables discovered and configured themes. Explicit `--theme` paths still load.
- `-nc`, `--no-context-files`<br>
Disables `AGENTS.md` and `CLAUDE.md` discovery.
Resource paths apply only to the current process. Relative paths resolve from the current working directory.
<a id="prompt-and-display-options"></a>
## Prompts and process
```sh
pi --append-system-prompt ./instructions.md
```
See [Configuration](configuration.md) for saved configuration, [Security](security.md#understand-project-trust) for project trust, and [Environment Variables](environment-variables.md) for process controls.
- `--system-prompt <text|path>`<br>
Replaces the default system prompt with text or the contents of an existing file.
- `--append-system-prompt <text|path>`<br>
Appends text or an existing file to the system prompt and is repeatable.
- `--tui-mode <mode>`<br>
Uses `regular` or `fullscreen` terminal mode.
- `--verbose`<br>
Shows verbose interactive startup information, overriding `quietStartup`.
- `-a`, `--approve`<br>
Trusts project-local configuration and resources for this process.
- `-na`, `--no-approve`<br>
Ignores trust-gated project-local configuration and resources for this process.
- `--offline`<br>
Disables automatic network activity, including model catalog refreshes. Equivalent to `PI_OFFLINE=1`.
- `-h`, `--help`<br>
Shows help, including flags registered by loaded extensions, then exits.
- `-v`, `--version`<br>
Shows the Pi version, then exits.
Extensions may register additional long-form options. Unknown short options are rejected.
## Package commands
```sh
pi install npm:@scope/package
```
See [Pi Packages](packages.md) for source formats, filtering, installation, and project scope.
### Common tasks
| Task | Command |
|---|---|
| Install a package | `pi install <source>` |
| List configured packages | `pi list` |
| Remove a package and its settings entry | `pi remove <source>` |
| Configure which package resources load | `pi config` |
Add `--local` or `-l` to `install`, `remove`, `uninstall`, or `config` to use project settings instead of global settings.
### Update Pi or packages
Running `pi update` without a target updates Pi itself.
| Task | Command |
|---|---|
| Update Pi | `pi update` |
| Update all installed packages | `pi update --extensions` |
| Update one installed package | `pi update <source>` |
| Refresh model catalogs | `pi update --models` |
| Update Pi and all installed packages | `pi update --all` |
Add `--force` to reinstall Pi when the selected update includes Pi.
### Aliases and command options
- `pi uninstall <source>` is an alias for `pi remove <source>`.
- `pi update --self`, `pi update self`, and `pi update pi` are aliases for `pi update`.
- `pi update --extension <source>` is an alias for `pi update <source>`.
- `-a`, `--approve` trusts project-local files for one command. `-na`, `--no-approve` ignores trust-gated project-local files.
- Append `-h` or `--help` to a command for its exact usage and option constraints.
## Credential commands
```sh
pi auth check --provider openai --json
```
Authentication commands require `--provider <provider>` or `--model <model>`. See [Provider Authentication](providers.md) for supported methods.
| Command | Description |
|---|---|
| `pi auth check` | Print `ready`, `not_ready`, or `invalid`; exit with status `0`, `1`, or `2`, respectively |
| `pi auth print-api-key` | Print the resolved API key |
| `pi auth print-bearer-token` | Print a resolved OAuth bearer token |
| Option | Applies to | Description |
|---|---|---|
| `--provider <provider>` | All | Resolve credentials for a provider |
| `--model <model>` | All | Resolve credentials from a model; may be combined with `--provider` |
| `--json` | `auth check` | Write the structured result as JSON |
| `--credentials` | `auth check` | Emit the resolved credential when ready |
| `--no-refresh` | `auth check` | Do not refresh expired OAuth credentials; refresh is the default |
| `--min-expiry <duration>` | `print-bearer-token` | Require remaining token lifetime using `ms`, `s`, `m`, or `h`, such as `30m` |
Credential-printing commands write secrets to stdout.