Povio Boards CLI

@povio/boards-cli provides boards-cli, a native Rust client for the Povio Boards hosted MCP server. It supports the same 64 callable MCP tools, with focused command help and agent guidance.

For approved archive/restore changes on owned boards with exact titles and keys, boards set-lifecycle --file PATH discovers targets, applies changes and verifies fresh complete lists on one connection. Optional focused instructions are available with boards-cli guide --workflow lifecycle or the @povio/boards-cli/lifecycle-guide export (LIFECYCLE_GUIDE.md). Select this entry for its matching scope; full project rules remain authoritative. Partial or uncertain writes require reconciliation, never automatic replay. This is not a transaction or a content/access audit.

Requires Node.js 20+ for the npm launcher. No Rust compiler or Bun runtime is needed after installation. Supported native platforms: macOS arm64/x64, Linux arm64/x64 (glibc), and Windows x64. Alpine/musl and Windows arm64 are not supported.

After an authorized release is available:

npm install -g @povio/boards-cli
boards-cli --version
boards-cli --help
boards-cli guide
boards-cli setup --agent both --scope project --skip-auth

Set BOARDS_MCP_URL explicitly to your operator-provided hosted MCP endpoint, including /mcp. There is no production fallback. Authenticate using boards-cli auth login --issuer URL, with the operator-provided OAuth issuer, or an explicitly supplied BOARDS_ACCESS_TOKEN. Never substitute an API key. Saved OAuth credentials use the OS credential store. Linux requires an unlocked Secret Service and D-Bus session. No plaintext fallback is used on keyring failure.

boards-cli guide returns the bundled agent guide in the normal JSON envelope (result.guide), without a network request. Ask your agent to read it before work. Installing or upgrading this package does not automatically edit agent configuration. Run setup explicitly in the workspace where the agent will work. Project setup writes .agents/skills/povio-boards-cli for Codex and/or .claude/skills/povio-boards-cli for Claude. Choose --agent codex, claude, both or none, and --scope project or global. --skip-auth is entirely offline. Without it, setup requires the configured server and verifies compatibility plus one authenticated read-only board listing before installing files. Interactive setup can offer browser login using an operator-provided issuer (--issuer URL); non-interactive setup never starts login. The same guide is also available as @povio/boards-cli/guide.

Customized installed guidance is preserved unless you explicitly use --replace. After reviewing an upgrade, refresh the selected agent/scope intentionally:

boards-cli setup --agent both --scope project --skip-auth --replace

This replaces both SKILL.md and operations.md for the selected agents, including local edits. Without --replace, matching copies remain unchanged and missing references are repaired. Start a new agent session and ask it to use the povio-boards-cli skill; installation cannot refresh an active conversation.

Use full scoped commands for offline help, for example:

boards-cli cards search --help
boards-cli cards create-batch --help
boards-cli cards update-batch --help

Batch writes are atomic within their supported board scope. Writes are not retried automatically. If a dispatched mutation reports an unknown outcome, read fresh state and reconcile before another write. Never blindly replay it.

The npm archive contains only the launcher/types, native executables, this README, agent guide and distribution manifest. No backend source, credentials, tests or benchmark artifacts are included. This package is UNLICENSED; public registry access does not grant permission to reuse its contents.

Confirmed exact title/key deletion can use boards delete-confirmed --confirm-title TEXT --confirm-key KEY after explicit user approval of permanent deletion. It discovers completely, deletes once with existing server checks and freshly verifies absence. Require complete:true and verified:true; reconcile uncertain/acknowledged-write errors before another mutation. Optional scoped entry: DELETION_GUIDE.md (guide --workflow deletion, package export ./deletion-guide). See docs/NATIVE-DELETION-RESULTS.md for the bounded real-agent comparison.

New-main integration (2026-10-29): 75 advertised MCP tools, all 75 integrated CLI tools. G1 adds boards archive BOARD, boards restore BOARD, and boards list --archived true|false. Mutations require owner/admin and write scope, retain content/access, and never retry automatically. Verify with fresh paginated lists. Group organization is implemented with groups list/create/update/delete/reorder and boards move; membership is implemented with group-shares list/create/remove. Group sharing grants no board access; verify membership separately from board access. N02 organization and N03 additive membership have scoped CLI-preferred samples; N01 lifecycle also has a scoped CLI-preferred sample; broader usages remain unmeasured. See docs/MAIN-TOOLS-INTEGRATION-2026-10-29.md.

Optional matching portfolio coordinator: groups setup --file PATH, with exact JSON {title,emoji,boardKeys,rename:{group,title},prioritize:true}. Creates one folder, arranges existing active boards, renames one owned unshared folder, puts new/renamed folders first/second and freshly verifies setup. Deletion/sharing remain separate; no retry/rollback. Inspect partial-write details before continuing. Other scope uses ordinary commands. See docs/N02-PORTFOLIO-RESULTS.md for the capped agent comparison.

Optional owned-folder membership coordinator: group-shares reconcile --file PATH, exact JSON {group,addEmails,cancelInvitationEmails}. Applies only approved new shares/ invitations and pending cancellations, then verifies fresh membership. No existing member removal, board access changes, new API, retries or rollback. Partial changes remain explicit; concurrent membership is not locked. Returns verified/complete, answer, verification and underlying receipts. See docs/N03-MEMBERSHIP-RESULTS.md for capped source-bound agent evidence and limitations. Ordinary commands cover other scope.

Optional reversible lifecycle coordinator: boards set-lifecycle --file PATH, exact JSON {changes:[{title,key,archived:true|false}]}. Copies explicitly requested state changes for1–100owned boards with exact titles/keys and opposite initial state; validates all targets before writes, uses existing MCP operations on one connection and freshly exhausts both active/archived lists. Require complete:true/verified:true; verifiedBoards contains fresh answer fields. No deletion, permission changes, retries or rollback; partial writes and concurrent-state limitations remain explicit. Other/admin scopes use ordinary commands. See docs/N01-LIFECYCLE-RESULTS.md and final global status.

Ordinary discovered-ID deletion can add --verify: boards delete UUID --confirm-title "User-confirmed title" --verify. It deletes once and freshly verifies complete active-board absence, returning verified/complete/answer. No retry/rollback or archived audit; failed proof can follow committed deletion. Inspect phase/writeAcknowledged/outcome and reconcile before further writes. Default deletion retains its original MCP output. The optional ORDINARY_DELETION_GUIDE.md entry is available through guide --workflow ordinary-deletion and the package ordinary-deletion-guide export. R01 measured fewer calls/input but CLI11.04s/MCP10.19s; it does not establish a latency win or automatic guide routing. Native delete-confirmed remains a separate workflow.

For an additive release plan using existing unassigned tickets, boards-cli roadmap plan-release --file release.json resolves approved selectors and verifies the full roadmap. Read roadmap plan-release --help and the full agent guide for the exact bounded manifest and partial-write recovery.

Optional handoff coordination: boards-cli handoff inspect --board-title "Exact board" --title "Exact ticket", then boards-cli handoff apply --file handoff.json. The agent selects the decision/blocker from full discussion; apply checks context freshness and verifies one new blockedBy link plus an approved internal note. See scoped help for manifest/scope and partial-write recovery. Measured latency improved, while uncached input increased; this is a conditional workflow.

For an operator-configured agent that needs only the verified deletion answer, BOARDS_DELETE_SUMMARY=1 with BOARDS_DELETE_AUDIT_PATH=/private/path/NEW-file.json reduces successful boards delete UUID --confirm-title TEXT --verify output. Full receipts are persisted to the new file (0600 on Unix); verification is unchanged and every error stays full. Missing/existing/unwritable audit paths fail before deletion; a later persistence failure reports acknowledged deletion and requires reconciliation. Use a unique protected file for each deletion. Default output is unchanged. R04 timing results and limitations are in docs/R04-DELETION-DRILL-RESULTS.md.

For approved new board roles plus separate folder visibility, boards-cli access onboard --file plan.json coordinates additive editor/viewer grants and verifies preserved private sibling-board exclusions. Read access onboard --help and the full agent guide for the exact owned/private scope, manifest and partial-write recovery. Existing-access reconciliation and permission changes use ordinary commands.

Optional scoped import guidance: boards-cli guide --workflow imports prints the bundled IMPORT_GUIDE.md for operator-selected new-estimate/expired-grant recovery. Use the full project instructions for broader scope; this does not change import permissions, writes, retry or recovery semantics.

For approved new-board imports, imports preview --package-url URL --review-token returns the full preview for separate review. Then imports apply-verified IMPORT_ID --review-token TOKEN --refreshed-package-url SAME_EXPORT_URL guards apply/recovery/fresh verification. Require complete:true/verified:true and use answer. No replay, polling or rollback; inspect ordinary imports get after any failure. See scoped import guidance.

For an approved new Service desk table queue plus an existing calendar's date/layout change, views save-service-desk --file PATH validates exact selectors, retains other settings and freshly verifies the complete saved view set. Use scoped command help for the strict manifest; require complete:true/verified:true. Shared settings are not transactional/version-guarded; reconcile partial results without replay or rollback.

Explicit ordinary plans

sequence run --file plan.json executes1–20explicit ordinary argv steps with supplied string vars and nonempty JSON-pointer expectations, on one connection/catalogue. It validates before dispatch and stops on any failure, retaining full receipts and prior checked write indices. No target/workflow selection, nested coordinators, file/projection commands, automatic fresh reads, retry or rollback. complete means the plan completed; supply final fresh reads and verify the complete requested state. Use sequence run --help for schema/recovery. guide --workflow ordinary-membership returns the optional entry, also exported as @povio/boards-cli/ordinary-membership-guide. The N03sample saved32.3%total input but was3.7%slower than MCP; uncached+7.0%,output+26.2%. This is opt-in, with no latency or billed-cost preference claim.