---
layout: docs
title: "`pidash` CLI Reference"
section: Pi Dash
order: 17
---

# `pidash` CLI Reference

Complete reference for the `pidash` binary. All commands, all flags, brief examples.

For the _guided_ setup walkthrough use [02 — Cloud Quickstart](/docs/pi-dash/cloud-quickstart). For the runner's internals see [07 — Runner architecture](/docs/pi-dash/runner-architecture).

## Global flags

Available on every command:

| Flag                  | Env                 | Default        | Purpose                                              |
| --------------------- | ------------------- | -------------- | ---------------------------------------------------- |
| `--config-dir <PATH>` | `PIDASH_CONFIG_DIR` | XDG config dir | Override config location                             |
| `--data-dir <PATH>`   | `PIDASH_DATA_DIR`   | XDG data dir   | Override data location                               |
| `--log <LEVEL>`       | `PIDASH_LOG`        | `info`         | Log level: `trace`, `debug`, `info`, `warn`, `error` |
| `--help`              | —                   | —              | Show help for any command                            |
| `--version`           | —                   | —              | Print version                                        |

## `pidash` (no subcommand)

First-run launcher. If no config exists, drops into `pidash auth login`. Otherwise prints help.

---

## Setup & auth

### `pidash login` / `pidash auth login`

Browser-based device-code login. Same UX as `gh auth login` / `stripe login`. `pidash login` is a top-level alias of `pidash auth login`: same flags, same flow, same stored token.

```
pidash login [--url <URL>] [--no-browser]
pidash auth login [--url <URL>] [--no-browser]
```

| Flag           | Purpose                                                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--url <URL>`  | Cloud base URL of a self-hosted instance. Omitted, reuses this host's configured `[daemon].cloud_url`, else defaults to `https://pidash.airepublic.com`. |
| `--no-browser` | Don't try to open the verification URL automatically.                                                                                                    |

Writes the CLI token to `config.toml`, then confirms the account and workspace and points you at the cloud URL. Registering a runner is a separate, explicit step — see `pidash runner add`.

### `pidash auth status`

Show who you're logged in as and which runners are registered on this host.

```
pidash auth status
```

### `pidash auth logout`

Revoke the CLI token server-side and clear it locally. `[[runner]]` blocks are left intact — the daemon keeps running under its own identity.

```
pidash auth logout [--local-only]
```

| Flag           | Purpose                                                                            |
| -------------- | ---------------------------------------------------------------------------------- |
| `--local-only` | Skip server-side revoke, just clear local token. Useful when cloud is unreachable. |

## Local config

### `pidash config set default-project <PROJECT>`

Set the local default project for non-interactive CLI calls (e.g. `pidash issue list` without `--project`).

```
pidash config set default-project <PROJECT_IDENTIFIER_OR_UUID>
```

---

## Runner management

### `pidash runner add`

Register a new runner. Uses the CLI token from `pidash auth login`.

```
pidash runner add --project <PROJECT> [--name <NAME>] [--workspace <SLUG>]
                  [--pod <POD>] [--working-dir <PATH>] [--agent codex|claude-code]
```

| Flag                     | Purpose                                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `--project <P>`          | Project identifier (slug or UUID). **Required.**                                                                                       |
| `--name <N>`             | Human-friendly runner name. Auto-generated if omitted.                                                                                 |
| `--workspace <S>`        | Workspace slug. Required if you belong to multiple workspaces.                                                                         |
| `--pod <P>`              | Pod within the project. Defaults to project's default pod.                                                                             |
| `--working-dir <P>`      | Working dir for this runner. A repo, an empty dir (cloned into on first run), or any task folder. Defaults to a path under `data_dir`.  |
| `--agent <K>`            | Which agent CLI the runner drives: `codex` (default), `claude-code`, `cursor-agent`, `open-claw`, `grok`, `muse-code`.                  |
| `--model <M>`            | Default LLM model for the agent. Omit to use the agent's own default.                                                                   |
| `--reasoning-effort <T>` | Codex reasoning tier (`low`/`medium`/`high`/`xhigh`). `--agent codex` only.                                                             |
| `--skip-agent-install`   | Don't auto-install the agent CLI if it's missing; you'll install it yourself.                                                           |

On the first runner: installs the OS service (systemd user unit / launchd agent / Windows scheduled task) and starts the daemon.

If the selected agent's CLI isn't installed, `runner add` installs it by invoking the vendor's own official install script (never a bundled binary), records the installed binary's absolute path in the runner config, and prints the one login step still needed. On any install failure it falls back to opening the vendor's install page. Pass `--skip-agent-install` to opt out. See the [runner README](https://github.com/The-AI-Republic/pi-dash/blob/55f45aa855f8961b21db57482764894195afa743/runner/README.md#agent-cli-auto-install) for details.

### `pidash runner list`

List runners configured on this machine.

```
pidash runner list
```

### `pidash runner remove`

Deregister a runner (cloud + local).

```
pidash runner remove <NAME> [--local-only] [-y|--yes]
```

| Flag           | Purpose                                                                            |
| -------------- | ---------------------------------------------------------------------------------- |
| `<NAME>`       | Runner name from `pidash runner list`. Must match a `[[runner]]` in `config.toml`. |
| `--local-only` | Skip cloud-side delete; just clean local config + data dir.                        |
| `-y`, `--yes`  | Skip the y/N confirm. Required for scripted callers.                               |

---

## Service lifecycle

### `pidash install`

Write or refresh the OS service unit. Safe to re-run after binary upgrades.

```
pidash install [--skip-linger]
```

| Flag            | Purpose                                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| `--skip-linger` | Linux only — skip `sudo loginctl enable-linger`. Without linger the daemon only starts at login, not at boot. |

### `pidash uninstall`

Remove the OS service unit. Local config + runner credentials are kept.

```
pidash uninstall
```

### `pidash start` / `pidash stop` / `pidash restart`

Control the installed service.

```
pidash start
pidash stop
pidash restart
```

### `pidash status`

Combined service-level + daemon-runtime status.

```
pidash status [--json]
```

| Flag     | Purpose                                |
| -------- | -------------------------------------- |
| `--json` | Print JSON instead of a human summary. |

If the daemon isn't running, prints just the service-level state and a note (instead of an IPC error).

### `pidash tui`

Attach the interactive Ratatui UI to the running daemon.

```
pidash tui [--tab <TAB>]
```

| Flag          | Purpose                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| `--tab <TAB>` | Open directly to a tab: `runner` (default), `config`, `runs`, or `approvals`. Accepts 1-based index `1`–`4`. |

Press `q` to quit; the daemon keeps running in the background.

### `pidash doctor`

Preflight checks: agent installed + on `PATH`, agent authed, git configured, cloud reachable.

```
pidash doctor [--json] [--runner <NAME>]
```

| Flag              | Purpose                                                                  |
| ----------------- | ------------------------------------------------------------------------ |
| `--json`          | Machine-readable report.                                                 |
| `--runner <NAME>` | Restrict per-runner checks to one runner. Daemon-wide checks always run. |

### `pidash update`

Swap the on-disk `pidash` binary for the latest GitHub release. Only works for cargo-dist installs (those leave an install receipt).

```
pidash update [--check] [--restart]
```

| Flag        | Purpose                                                                    |
| ----------- | -------------------------------------------------------------------------- |
| `--check`   | Report whether an update is available, don't swap.                         |
| `--restart` | After swap, restart the daemon so the new binary takes effect immediately. |

Without `--restart`, the swap only takes effect on the next natural restart (`pidash restart`, reboot, service respawn). The running process is never disturbed.

For a one-command manual upgrade, run `pidash update --restart` when the runner is idle.

### `pidash remove --all`

Full teardown: stop service → uninstall service unit → deregister with cloud → delete local `config.toml` + credentials.

```
pidash remove --all [--local-only]
```

| Flag           | Purpose                                                                             |
| -------------- | ----------------------------------------------------------------------------------- |
| `--all`        | **Required.** Explicit confirmation that you want to wipe ALL runners on this host. |
| `--local-only` | Delete local state without contacting the cloud.                                    |

> To drop a single runner instead, use `pidash runner remove <name>`.

---

## Workspace / project / context

### `pidash workspace me`

Verify CLI credentials end-to-end (token + cloud reachability + TLS + active user). The probe `pidash doctor` uses.

```
pidash workspace me
```

### `pidash project list`

List projects in the active workspace. Prints JSON.

```
pidash project list
```

Pi Dash writes two `context.md` files so an agent can tell which project a
directory belongs to and what else exists in the workspace:

- **Working-dir** `<working_dir>/.pidash/context.md` (`scope: "project"`) — the
  single project that working directory belongs to. Authoritative for "which
  project am I working in". Written at `runner add` and when the daemon resolves
  a workspace, and excluded from the repo via `$GIT_DIR/info/exclude` (never
  `.gitignore`).
- **Machine-level** `~/.pidash/context.md` (`scope: "machine"`) — every project
  in every workspace this machine is bound to, keyed by workspace slug. The
  lookup table for "what else exists in this workspace" and the fallback when
  there is no working-dir file. Written on `auth login`, at `runner add`, and
  when the daemon resolves a workspace, and refreshable with
  `pidash context refresh`. Its location follows `PIDASH_CONFIG_DIR` when set,
  otherwise `~/.pidash`.

Both files carry a `generated_at` RFC 3339 UTC stamp, and each project carries a
`repo_url`.

### `pidash context init`

Write the working-dir `.pidash/context.md` for a local directory, scoped to one
project.

```
pidash context init --project <PROJECT> [--workspace <PATH>]
```

| Flag              | Purpose                                             |
| ----------------- | --------------------------------------------------- |
| `--project <P>`   | Project identifier or UUID. **Required.**           |
| `--workspace <P>` | Local workspace dir. Defaults to current directory. |

### `pidash context refresh`

Rewrite the machine-level `~/.pidash/context.md` for the bound workspace,
replacing that workspace's project list wholesale (pruning deleted projects) and
leaving other workspaces intact.

```
pidash context refresh
```

---

## Work items

### `pidash issue get <IDENTIFIER>`

Fetch one work item. Prints full JSON. The payload includes an absolute `url`
pointing at the issue in the web UI, built from the deployment's `WEB_URL` (or
`APP_BASE_URL`); the field is omitted when neither is configured.

```
pidash issue get ENG-42
```

### `pidash issue create`

Create a work item under a project.

```
pidash issue create --title <TITLE> [--project <P>]
                    [--description <D> | --description-file <PATH>]
                    [--priority <P>] [--state <S>]
```

| Flag                        | Purpose                                                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `--title <T>`               | **Required.**                                                                                                                   |
| `--project <P>`             | Project identifier or UUID. If omitted: `PIDASH_PROJECT_ID` env → local `default_project` → workspace default.                  |
| `--description <D>`         | Description as markdown.                                                                                                        |
| `--description-file <PATH>` | Read the markdown description from a file; `-` reads stdin. Conflicts with `--description`. Empty input is an error (exit `2`). |
| `--priority <P>`            | `none` \| `low` \| `medium` \| `high` \| `urgent`.                                                                              |
| `--state <S>`               | Initial state — name (case-insensitive) or UUID.                                                                                |

**How descriptions land.** The CLI sends the markdown as `description_markdown`, and the server converts it with the same markdown → rich-text converter the page commands use. Headings, nested lists, task-list checkboxes, fenced code blocks (with language) and tables keep their structure in the web editor. For a long or multi-line body, write it to a file or pipe it instead of quoting it on the command line:

```
generate-body | pidash issue create --project ENG --title "Cold start: crate foo" --description-file -
```

### `pidash issue list --project <P>`

List work items in a project. Returns the paginated envelope `{count, next_cursor, prev_cursor, results}`.

```
pidash issue list --project <P> [--cursor <C>] [--per-page <N>] [--order-by <F>]
                  [--state <S>[,<S>...]] [--state-group <G>[,<G>...]] [--parent <PROJ-123|UUID|none>]
                  [--label <L>[,<L>...]] [--priority <P>[,<P>...]] [--fields <F>[,<F>...]]
```

| Flag                | Purpose                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `--project <P>`     | **Required.**                                                                                                    |
| `--cursor <C>`      | Pagination cursor from a prior page's `next_cursor`.                                                             |
| `--per-page <N>`    | Items per page. Server default if omitted.                                                                       |
| `--order-by <F>`    | Sort field, e.g. `-created_at` (default), `priority`, `state__name`.                                             |
| `--state <S>`       | State names (case-insensitive) and/or UUIDs, comma-separated. An unknown name fails with the valid names listed. |
| `--state-group <G>` | `backlog` \| `unstarted` \| `started` \| `review` \| `test` \| `completed` \| `cancelled`, comma-separated, plus shortcuts `open` (`backlog,unstarted,started,review,test`), `closed` (`completed,cancelled`) and `all` (no filter). Aliases may be mixed with concrete groups. Defaults to `open` when neither `--state` nor `--state-group` is given. |
| `--parent <P>`      | Sub-issues of this parent (`PROJ-123`, resolved to a UUID client-side, or a UUID); `none` for top-level only.    |
| `--label <L>`       | Label names (case-insensitive) and/or UUIDs, comma-separated.                                                    |
| `--priority <P>`    | `urgent` \| `high` \| `medium` \| `low` \| `none`, comma-separated.                                              |
| `--fields <F>`      | Return only these fields per item, e.g. `id,sequence_id,name,state,parent`.                                      |

Values within one flag OR together; different flags AND together. With neither `--state` nor `--state-group`, `issue list` defaults to `open` (`backlog,unstarted,started,review,test`); the response includes `"state_group": "open"` so agents know closed items were excluded. Use `--state-group closed` for done/cancelled, or `--state-group all` for today's behaviour (every item). An explicit `--state` or `--state-group` disables the default. Example — Backlog sub-issues of an epic, small payload:

```
pidash issue list --project ENG --parent ENG-12 --state Backlog --fields id,sequence_id,name,state
```

The same filters are available as query parameters on `GET /api/v1/workspaces/<slug>/projects/<project>/work-items/`: `state`, `state_group`, `parent` (`null` for top-level), `labels`, `priority`, `assignees` (user UUIDs), plus `fields` and `expand`.

### `pidash issue patch <IDENTIFIER>`

Update fields. Pass only the fields you want to change.

```
pidash issue patch ENG-42 [--state <S>] [--title <T>]
                          [--description <D> | --description-file <PATH>] [--priority <P>]
                          [--work-type <K> | --clear-work-type]
```

| Flag                        | Purpose                                                                                                                                                                                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--state <S>`               | State name (case-insensitive) or UUID.                                                                                                                                                                          |
| `--title <T>`               | New title.                                                                                                                                                                                                      |
| `--description <D>`         | New description as markdown. `--description ""` clears it.                                                                                                                                                      |
| `--description-file <PATH>` | Read the new markdown description from a file; `-` reads stdin. Empty input is an error.                                                                                                                        |
| `--priority <P>`            | `none` \| `low` \| `medium` \| `high` \| `urgent`.                                                                                                                                                              |
| `--work-type <K>`           | Work type key (e.g. `software`, `general`) — selects the per-work-type agent guidance. The server validates the key, and rejects agent-attributed changes while the issue is In Progress / In Review / In Test. |
| `--clear-work-type`         | Clear the per-issue work type; the issue inherits the project's default.                                                                                                                                        |

A description flag replaces the whole body. It is converted server-side, the same way as for `issue create`.

### `pidash issue move <IDENTIFIER> --project <P>`

Move a work item into another project in the same workspace.

```
pidash issue move ENG-42 --project OPS
```

---

## Comments

### `pidash comment list <IDENTIFIER>`

List comments on a work item.

```
pidash comment list ENG-42
```

### `pidash comment add <IDENTIFIER>`

Post a new comment.

```
pidash comment add ENG-42 (--body <BODY> | --body-file <PATH>) [--as-agent <NAME>] [--agent-run-id <UUID>]
```

| Flag                    | Purpose                                                                 |
| ----------------------- | ----------------------------------------------------------------------- |
| `--body <B>`            | Comment body (plain text or markdown).                                  |
| `--body-file <PATH>`    | Read body from file.                                                    |
| `--as-agent <NAME>`     | Mark the comment as spoken by an AI agent with this display name.       |
| `--agent-run-id <UUID>` | Record the Pi Dash agent run UUID that produced the agent-spoken reply. |

### `pidash comment update <IDENTIFIER> <COMMENT_UUID>`

Edit an existing comment owned by you.

```
pidash comment update ENG-42 <COMMENT_UUID> (--body <BODY> | --body-file <PATH>)
```

---

## AI assistant

### `pidash ai <COMMAND>`

Send a command to the AI assistant in your connected Pi Dash cloud and print its
reply. This is the CLI door to the same built-in assistant available on the web
landing page — it operates Pi Dash **as you** (querying and creating projects,
issues, and comments, and dispatching coding runs), scoped to your permissions.

Everything after `ai` is joined into one message, so quoting is optional:

```
pidash ai "create an issue in ENG for the flaky login test and set priority high"
pidash ai what changed on ENG-42 this week
```

Because everything after `ai` is treated as the message, put `--json` and
`--timeout` **before** the command (e.g. `pidash ai --json what changed on ENG-42`);
otherwise they are swallowed into the message text.

The command opens a fresh assistant thread, sends your message, waits for the
turn to finish (streaming tool activity to stderr), and prints the assistant's
answer on stdout.

| Flag               | Purpose                                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `--json`           | Emit the raw turn result (`{thread_id, turn_id, messages}`) as one JSON document instead of the human transcript.                |
| `--timeout <SECS>` | Give up waiting after this many seconds (default `180`). The turn may still finish in the cloud; only the local wait is bounded. |

**BYOK (bring your own key).** The assistant is BYOK-only: you must configure an
LLM provider and API key under **Settings → AI assistant** in Pi Dash. If it is
not set up, `pidash ai` prints a clear reason and exits non-zero rather than
hanging:

```
{"error":"the Pi Dash AI assistant is not set up yet. It is BYOK (bring your own key): add your LLM provider and API key under Settings → AI assistant in Pi Dash, then run `pidash ai` again"}
```

Exit code is `0` when the assistant replies, and non-zero when the assistant
reports an error, the wait times out, or BYOK is unconfigured — so scripts can
branch on it.

---

## Pages

Project pages are a project-scoped wiki — decisions, conventions, stage plans. `list` and `get` read pages; `create`, `update`, `archive` and `unarchive` write them. Page bodies go in and come out as markdown.

### `pidash page list --project <P>`

List the pages of a project. Returns the paginated envelope `{count, next_cursor, prev_cursor, results}` carrying page **metadata only** (`id`, `name`, `parent`, `owned_by`, `access`, `is_locked`, `archived_at`, `created_at`, `updated_at`) — read a single page to get its body.

```
pidash page list --project ENG [--cursor <C>] [--per-page <N>] [--include-archived]
```

| Flag                 | Purpose                                              |
| -------------------- | ---------------------------------------------------- |
| `--project <P>`      | **Required.** Project slug (`ENG`) or project UUID.  |
| `--cursor <C>`       | Pagination cursor from a prior page's `next_cursor`. |
| `--per-page <N>`     | Items per page. Server default if omitted.           |
| `--include-archived` | Also list archived pages. Excluded by default.       |

Pages another member marked private are not listed. A caller who is not a member of the project gets exit code `3`.

### `pidash page get <PAGE_UUID> --project <P>`

Fetch one page. Prints the JSON envelope: the list metadata plus `description_html`, `description_stripped`, and `description_markdown`. The markdown is rendered server-side, so the CLI, the REST API and the MCP page tool all return the same text.

```
pidash page get 550e8400-e29b-41d4-a716-446655440000 --project ENG
```

| Flag            | Purpose                                                    |
| --------------- | ---------------------------------------------------------- |
| `--project <P>` | **Required.** Project slug (`ENG`) or project UUID.        |
| `--body-only`   | Print only the markdown body instead of the JSON envelope. |

`--body-only` is what an agent wants when it intends to read the page as a document:

```
pidash page get 550e8400-e29b-41d4-a716-446655440000 --project ENG --body-only > ./conventions.md
```

A page UUID that does not exist — or one that belongs to another member's private page — exits `4` (not found); the API deliberately does not distinguish the two.

### `pidash page create --project <P> --title <T>`

Create a page. Prints the created page (the same envelope as `page get`).

```
pidash page create --project ENG --title "Release checklist" --body-file ./checklist.md
```

| Flag                       | Purpose                                                       |
| -------------------------- | ------------------------------------------------------------- |
| `--project <P>`            | **Required.** Project slug (`ENG`) or project UUID.           |
| `--title <T>`              | **Required.** Page title. Must not be blank.                  |
| `--body <MD>`              | Page body as markdown. Mutually exclusive with `--body-file`. |
| `--body-file <PATH>`       | Read the markdown body from a file; `-` reads stdin.          |
| `--parent <PAGE_UUID>`     | Nest the new page under this page.                            |
| `--access public\|private` | Page visibility. Server default (public) if omitted.          |

Pipe a generated body straight in:

```
generate-notes | pidash page create --project ENG --title "X" --body-file -
```

### `pidash page update <PAGE_UUID> --project <P>`

Change a page. Only the fields you pass are sent; at least one is required — an update with no field flags exits `2` without contacting the server. A body flag replaces the whole body (there is no append). Prints the updated page.

```
pidash page update 550e8400-e29b-41d4-a716-446655440000 --project ENG --body-file ./conventions.md
```

| Flag                                 | Purpose                                                                                 |
| ------------------------------------ | --------------------------------------------------------------------------------------- |
| `--project <P>`                      | **Required.** Project slug (`ENG`) or project UUID.                                     |
| `--title <T>`                        | New title.                                                                              |
| `--body <MD>` / `--body-file <PATH>` | New markdown body (`-` reads stdin). Mutually exclusive. An empty body clears the page. |
| `--parent <PAGE_UUID>`               | Move the page under this page. Mutually exclusive with `--clear-parent`.                |
| `--clear-parent`                     | Make the page top-level (sends `parent: null`).                                         |
| `--access public\|private`           | Change visibility. Only the page owner may do this.                                     |

### `pidash page archive <PAGE_UUID> --project <P>` / `pidash page unarchive <PAGE_UUID> --project <P>`

Archive a page, or restore an archived one. Both print the page afterwards. Archived pages drop out of `page list` unless `--include-archived` is passed, and cannot be edited until unarchived.

```
pidash page archive 550e8400-e29b-41d4-a716-446655440000 --project ENG
pidash page unarchive 550e8400-e29b-41d4-a716-446655440000 --project ENG
```

**Errors.** Page ids and `--parent` must be UUIDs; anything else exits `2` without a request, as does `--body` together with `--body-file` (a usage error from the argument parser). Server-side:

| Status | Exit | When                                                                     |
| ------ | ---- | ------------------------------------------------------------------------ |
| 400    | `2`  | Invalid field (e.g. a parent page from another project).                 |
| 409    | `2`  | The page is locked or archived.                                          |
| 403    | `3`  | Not a project member, or changing `--access` on a page you do not own.   |
| 404    | `4`  | Page does not exist, or is another member's private page.                |
| 503    | `5`  | The live document service is unavailable (body writes only — see below). |

**How body writes land.** The page editor is collaborative, so a page's content lives in a collaborative document (`description_binary`) alongside the `description_html` / `description_json` renderings. A body write sends markdown; the server regenerates all three through the live document service. If that service is unavailable the write fails with `503` (exit `5`) and nothing is changed — retry later.

**Known limitation.** If a human has the page open in the editor while an agent updates its body, the editor's next save can overwrite the agent's edit. Prefer writing pages nobody is editing, and re-read with `page get` afterwards if it matters.

---

## States

### `pidash state list [PROJECT_OR_ISSUE]`

List workflow states for a project. Without an argument, uses the current issue context from `PIDASH_ISSUE_IDENTIFIER`.

```
pidash state list             # uses current issue context
pidash state list ENG         # project slug
pidash state list ENG-42      # via work-item identifier
pidash state list <UUID>      # project UUID
```

---

## Hidden / internal

### `pidash __run`

Internal daemon entry point. Invoked by systemd / launchd / Windows scheduled task via the generated unit file. **Not a user-facing command.**

---

## Exit codes

`issue`, `comment`, `page`, `state`, `workspace`, `project`, `context` print JSON on stdout and JSON on stderr for errors. Their exit codes follow `api_client::EXIT_*` constants — non-zero on any error.

`ai` prints its reply as human-readable text on stdout (or JSON with `--json`), streams tool activity to stderr, and prints a `{"error": ...}` line to stderr on failure. It exits `0` when the assistant replies and non-zero otherwise (BYOK unconfigured, assistant error, or local timeout).

Other commands return `0` on success and surface anyhow errors on failure (non-zero exit).

## Common environment variables

| Variable                  | Used by        | Purpose                                  |
| ------------------------- | -------------- | ---------------------------------------- |
| `PIDASH_CONFIG_DIR`       | All            | Override config dir                      |
| `PIDASH_DATA_DIR`         | All            | Override data dir                        |
| `PIDASH_LOG`              | All            | Log level                                |
| `PIDASH_PROJECT_ID`       | `issue create` | Default project when `--project` omitted |
| `PIDASH_ISSUE_IDENTIFIER` | `state list`   | Default issue context                    |

## Common file locations

| What                   | Linux / macOS                               | Windows                                     |
| ---------------------- | ------------------------------------------- | ------------------------------------------- |
| Config + CLI token     | `~/.config/pidash/config.toml`              | `%APPDATA%\pidash\config.toml`              |
| Per-runner credentials | `<data_dir>/runners/<rid>/credentials.toml` | `<data_dir>\runners\<rid>\credentials.toml` |
| Run transcripts        | `<data_dir>/runners/<rid>/history/`         | `<data_dir>\runners\<rid>\history\`         |
| IPC socket / pipe      | `$XDG_RUNTIME_DIR/pidash/...`               | local named pipe                            |

All secrets and the IPC socket are `0600` on Unix.
