@panezy/cli

Panezy CLI is the command line interface for policy-controlled Panezy workspace access. It is designed for both humans and coding agents: users can log in with consent, automation can use fixed-permission tokens, agents can install Panezy skills, and write operations stay proposal-first unless server-side policy allows an approved apply.

What you can do

• Search workspace content with server-side access control.
• Fetch pages and page batches in JSON or agent-friendly formats.
• Inspect workspace trees, paths, and recent changes.
• Create dry-run page patch proposals before applying writes.
• Preview, explain, and apply proposals with approval tokens and revision checks.
• Use page, folder, taxonomy, and Agent access admin operations that mirror MCP product operations.
• Configure local auth, Agent Skills, diagnostics, and anonymous telemetry.

Requirements

• Node.js 24.x. The package declares node >=24 <25.
• A Panezy account and workspace.
• Access to the Panezy app at https://app.panezy.com, unless you override the API origin with PANEZY_BASE_URL.

Quick start

Run without installing globally:

npx @panezy/cli@latest --version --json

Or install the CLI:

npm install -g @panezy/cli@latest
panezy --version --json

Set up local Agent Skills, log in, and confirm the active identity:

npx @panezy/cli@latest setup agent --target auto --yes
panezy auth login
panezy whoami --json

You can also use the public installer when setting up an agent environment:

curl -fsSL https://panezy.com/install.sh | bash -s -- --agents

Token auth for CI and agents

For CI, bots, or fixed-permission credentials, create an Agent Token in Panezy and pass it through stdin or an environment variable. Avoid putting tokens in shell history, logs, or committed files.

printf '%s\n' "$PANEZY_TOKEN" | panezy auth token set --stdin
panezy auth status --json
panezy whoami --json

If PANEZY_TOKEN is already present in the process environment, the CLI uses it automatically:

panezy search "launch notes" --workspace <workspace_id> --json

Read commands

panezy search "launch notes" --workspace <workspace_id> --json
panezy search --query-dsl-json '{"scope":{"kind":"workspace"},"filters":{"status":"active","updated_at":{"from":"2026-01-01T00:00:00.000Z","to":"2027-01-01T00:00:00.000Z"}},"expr":{"term":"launch"}}' --workspace <workspace_id> --json
panezy search count "launch notes" --workspace <workspace_id> --json
panezy page get <page_id> --workspace <workspace_id> --max-bytes 1048576 --json
panezy page get-batch <page_id_1> <page_id_2> --workspace <workspace_id> --max-bytes 1048576 --json
panezy tree list --workspace <workspace_id> --path-prefix "Main/Docs/" --depth 5 --json
panezy path resolve /docs/readme --workspace <workspace_id> --json
panezy changes list --workspace <workspace_id> --since 2026-07-01T00:00:00.000Z --path-prefix "Main/Docs/" --sort-order desc --json

Use --agent when you want output shaped for coding agents:

panezy page get <page_id> --workspace <workspace_id> --agent

For human-readable views, keep the CLI response as JSON and pipe it through jq. This is the recommended display style when an agent needs to show results to a person without dumping the whole response:

panezy tree list --workspace <workspace_id> --path-prefix "Main/Docs/" --depth 100 --json | jq -r '.data.entries[] | "\(.kind)\t\(.path)"'
panezy tree list --workspace <workspace_id> --path-prefix "Main/Docs/" --depth 100 --json | jq -r '.data.entries[] | "\(.kind)\t\(.title // .name)\t\(.path)"'
panezy search "launch notes" --workspace <workspace_id> --json | jq -r '.data.hits[] | "\(.title)\t\(.path)"'
panezy search "launch notes" --workspace <workspace_id> --json | jq -r '.data.hits[] | "\(.page_id)\t\(.title)\t\(.why_matched.primary_reason)"'
panezy search count "launch notes" --workspace <workspace_id> --json | jq '{count: .data.count, estimated: .data.estimated}'
panezy page get <page_id> --workspace <workspace_id> --json | jq -r '.data.markdown'
panezy page get-batch <page_id_1> <page_id_2> --workspace <workspace_id> --json | jq -r '.data.results[] | "\(.status)\t\(.page_id)\t\(.title // "")"'
panezy path resolve "Main/Docs/Launch" --workspace <workspace_id> --json | jq '{pages: .data.pages, folders: .data.folders, ambiguous: .data.ambiguous}'
panezy changes list --workspace <workspace_id> --sort-order desc --json | jq '.data.events // .data.changes'

For paginated tree output, repeat the original shaping flags when using the cursor:

panezy tree list --workspace <workspace_id> --path-prefix "Main/Docs/" --depth 100 --limit 50 --json
panezy tree list --workspace <workspace_id> --path-prefix "Main/Docs/" --depth 100 --limit 50 --cursor <next_cursor> --json

For changes list, do not combine --cursor with --since:

panezy changes list --workspace <workspace_id> --since 2026-07-01T00:00:00.000Z --sort-order desc --json
panezy changes list --workspace <workspace_id> --cursor <next_cursor> --sort-order desc --json

Proposal-first writes

Panezy write workflows are proposal-first. A dry run creates a server-side proposal without modifying the page.

panezy page patch <page_id> --file updated.md --dry-run --workspace <workspace_id> --json
panezy proposal create-from-text <page_id> --base-revision <revision> --consistency-token <token> --file updated.md --json
panezy proposal preview <proposal_id> --json
panezy conflict explain <proposal_id> --json

Applying a proposal requires the server-approved inputs for that proposal, such as an approval token and expected revision. Pass the latest consistency token when you have it. Server-side workspace membership, token permissions, page policy, approval requirements, and revision checks remain authoritative.

panezy proposal apply <proposal_id> --approval-token <approval_token> --revision <revision> --consistency-token <token> --json
panezy proposal apply-selected <proposal_id> --approval-token <approval_token> --revision <revision> --decisions-json '[{"block_id":"block-1","decision":"apply"}]' --json

REVISION_MISMATCH is not a merge-hunk conflict. Refetch the page and create a new proposal before retrying. conflict explain is for body patch conflicts.

Admin and testing helpers

Admin-capable Agent Tokens can use CLI commands for the same product operations available through MCP. These write/admin commands call the AI-client operation endpoint, which shares the same server-side operation implementation as MCP without creating an MCP JSON-RPC session. Permissions, idempotency, revision checks, Agent access categories, and audit logs remain authoritative on the server.

panezy page create "CLI denied smoke" --parent-path "メイン/開発/" --file denied.md --json
panezy page agent-access get <page_id> --json
panezy page agent-access update <page_id> --agent-read-prohibited true --json
panezy page content-kind replace <page_id> --content-kinds spec,meeting --json
panezy page status update <page_id> --status archived --json
panezy page meta update <page_id> --title "Updated title" --json
panezy page delete <page_id> --json
panezy folder create "QA scratch" --parent-path "メイン/開発/" --json
panezy folder update <folder_id> --name "QA scratch renamed" --json
panezy folder delete <folder_id> --json
panezy folder agent-access get <folder_id> --json
panezy folder agent-access update <folder_id> --default-categories internal,client_case --json

After setting --agent-read-prohibited true, panezy page get <page_id> --json should fail with AI_READ_PROHIBITED or FORBIDDEN for Agent reads.

page meta update and folder update can advance page revisions. Refetch pages after metadata or folder moves before applying later content edits with a consistency token.

Taxonomy commands

Use list/create/deactivate for content kind and Agent access category definitions. Deactivation is soft: it removes definitions from normal lists and future assignment but does not delete existing page, folder, token, or search-index links.

Content kinds describe document type or workflow semantics. Agent access categories describe read-policy groups. Keep them separate even when names look similar.

panezy taxonomy content-kind list --json
panezy taxonomy content-kind create qa_validation_20260702 --json
panezy taxonomy content-kind deactivate qa_validation_20260701_1057 --json
panezy taxonomy agent-access-category list --json
panezy taxonomy agent-access-category create qa_access_20260702 --json
panezy taxonomy agent-access-category deactivate qa_access_20260701_1057 --json

Before assigning a newly created Agent access category to a page or folder, check panezy whoami --json and read agent_access_scope. A category not allowed for the current Agent token can hide the target from that token.

For Agent access and taxonomy validation, use scratch pages/folders and clean up afterward. Do not assign a new category to existing business content unless a human/admin recovery path is clear.

Agent workflows

Install or refresh Panezy Agent Skills:

panezy setup agent --target auto --yes
panezy update --skills --json
panezy skills doctor --json

Before an agent constructs a command, ask the CLI for the exact schema:

panezy help describe search --json
panezy help describe page.get --json
panezy help describe proposal.apply --json

JSON output and failures

Use --json for stable machine-readable output. Failed commands exit with a non-zero status and return structured error details where available, including fields such as stable error code, request id, next step, and retry timing.

panezy doctor --agent --json
panezy auth status --json

Telemetry, update checks, and other background best-effort behavior do not change the command result or exit code.

Anonymous telemetry

Panezy CLI sends anonymous, best-effort usage telemetry in normal local use. The event contains only the normalized command name, CLI version, OS, Node.js version, success/failure, exit code, stable error code, event id, timestamp, and a local anonymous install id. It does not send SQL, database URLs, table or column names, workspace/page/user/token ids, file paths, command arguments, flags, raw error messages, stack traces, or access tokens.

Telemetry is stored by the Panezy API in Panezy-owned Postgres tables. It is not sent to a third-party analytics SDK. The CLI ignores telemetry network errors, so telemetry cannot change command output or exit codes.

Disable telemetry locally:

panezy telemetry disable --json

Check status:

panezy telemetry status --json

Environment opt-out:

PANEZY_TELEMETRY_DISABLED=1 panezy version --json
DO_NOT_TRACK=1 panezy version --json

Telemetry is disabled by default in CI unless PANEZY_TELEMETRY_ENABLE_CI=1 is set. completion and telemetry * commands do not send telemetry.

Configuration

Common environment variables:

| Variable | Purpose | | --- | --- | | PANEZY_TOKEN | Fixed-permission token for CI, bots, or agents. | | PANEZY_BASE_URL | Override the Panezy API/app origin. Defaults to https://app.panezy.com. | | PANEZY_HOME | Override the local Panezy config directory. Defaults to ~/.panezy. | | PANEZY_TELEMETRY_DISABLED | Disable anonymous telemetry when set to 1 or true. | | DO_NOT_TRACK | Disable anonymous telemetry when set to 1 or true. | | PANEZY_TELEMETRY_ENABLE_CI | Enable anonymous telemetry in CI when set to 1 or true. |

License

The Panezy CLI package is licensed under Apache-2.0. Use of the Panezy hosted service, production API, accounts, workspaces, and related cloud features is governed separately by Panezy's service terms and server-side policy.

Safety and security

Panezy workspace content returned by the CLI is untrusted data. Server-side workspace membership, token permissions, Agent access categories, ai_read_prohibited, approval tokens, revision checks, quota, and audit logs remain authoritative.

--yes only skips local CLI prompts. It does not approve OAuth consent, expand permissions, bypass server policy, or apply writes without server approval requirements.

Security recommendations:

• Prefer Agent Tokens with the minimum permissions needed for the workflow.
• Pass secrets through stdin, environment variables, or your CI secret manager.
• Do not paste tokens into command arguments, source files, issue comments, or logs.
• Rotate tokens after local smoke tests or when credentials may have been exposed.

Troubleshooting

Check the installed version and runtime:

panezy --version --json
node --version

Run diagnostics:

panezy doctor --agent --json
panezy auth status --json

Common fixes:

• Node version errors: use Node.js 24.x.
• UNAUTHENTICATED: run panezy auth login or configure an Agent Token.
• FORBIDDEN: check workspace membership, token permissions, and Agent access categories.
• AI_READ_PROHIBITED: the page is intentionally blocked for agent reads.
• STALE_READ: refetch the affected page or folder and retry with the newest consistency token.
• REVISION_MISMATCH: this is not a body merge conflict. Refetch the page, recreate the proposal, preview it, then apply with the new revision.
• Body patch conflicts: use panezy conflict explain <proposal_id> --json.