Markdown

pidash CLI Reference

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

For the guided setup walkthrough use 02 — Cloud Quickstart. For the runner’s internals see 07 — Runner architecture.

Global flags#

Available on every command:

FlagEnvDefaultPurpose
--config-dir <PATH>PIDASH_CONFIG_DIRXDG config dirOverride config location
--data-dir <PATH>PIDASH_DATA_DIRXDG data dirOverride data location
--log <LEVEL>PIDASH_LOGinfoLog 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]
FlagPurpose
--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-browserDon’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]
FlagPurpose
--local-onlySkip 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]
FlagPurpose
--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-installDon’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 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]
FlagPurpose
<NAME>Runner name from pidash runner list. Must match a [[runner]] in config.toml.
--local-onlySkip cloud-side delete; just clean local config + data dir.
-y, --yesSkip 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]
FlagPurpose
--skip-lingerLinux 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]
FlagPurpose
--jsonPrint 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>]
FlagPurpose
--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>]
FlagPurpose
--jsonMachine-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]
FlagPurpose
--checkReport whether an update is available, don’t swap.
--restartAfter 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]
FlagPurpose
--allRequired. Explicit confirmation that you want to wipe ALL runners on this host.
--local-onlyDelete 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>]
FlagPurpose
--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>]
FlagPurpose
--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>...]]
FlagPurpose
--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]
FlagPurpose
--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-typeClear 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>]
FlagPurpose
--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.

FlagPurpose
--jsonEmit 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]
FlagPurpose
--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-archivedAlso 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
FlagPurpose
--project <P>Required. Project slug (ENG) or project UUID.
--body-onlyPrint 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
FlagPurpose
--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\|privatePage 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
FlagPurpose
--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-parentMake the page top-level (sends parent: null).
--access public\|privateChange 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:

StatusExitWhen
4002Invalid field (e.g. a parent page from another project).
4092The page is locked or archived.
4033Not a project member, or changing --access on a page you do not own.
4044Page does not exist, or is another member’s private page.
5035The 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#

VariableUsed byPurpose
PIDASH_CONFIG_DIRAllOverride config dir
PIDASH_DATA_DIRAllOverride data dir
PIDASH_LOGAllLog level
PIDASH_PROJECT_IDissue createDefault project when --project omitted
PIDASH_ISSUE_IDENTIFIERstate listDefault issue context

Common file locations#

WhatLinux / macOSWindows
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.

Search Docs and Blog