@wavyx/pdcli 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to `pdcli` are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow
 [SemVer](https://semver.org/).
 
+## [0.7.0] - 2026-06-05
+
+### Added
+
+- `default_output` profile config key is now honored: set
+  `pdcli config set default_output json` and every command (including
+  error output) defaults to that format when no `--output` flag is given.
+  An explicit flag still wins; invalid stored values fall back to the
+  table-in-TTY / JSON-when-piped default.
+- Docs website redesigned with the "Clarity" design system: new landing
+  page (animated terminal, quickstart, feature grid, live CLI stats),
+  light-first theme with dark mode, custom header/footer, social cards,
+  and brand fonts (Plus Jakarta Sans + JetBrains Mono) across all pages.
+- Homepage stats (version, command/topic/format counts) are generated
+  from the CLI manifest at docs-build time so they can never drift.
+
+### Fixed
+
+- Command-reference, config, and exit-code tables on the docs site
+  rendered as raw pipe characters; all GFM tables now render properly.
+- Documentation corrected against the implementation: autocomplete
+  shells, exit-code 64 semantics, JSON error-output trigger, rate-limit
+  header behavior, `--company`/`--api-token` flag scoping, and the
+  audit `--verbose` example.
+- Accessibility on the docs site: theme-toggle labeling, decorative
+  terminal/SVG content hidden from screen readers, heading hierarchy,
+  and WCAG AA contrast for footer and small-text elements.
+
+## [0.6.0] - 2026-06-04
+
+### Added
+
+- Documentation site (Astro + Starlight) at wavyx.github.io/pdcli:
+  quickstarts (including a dedicated AI-agent quickstart), guides for every
+  feature area, automation recipes, concepts, and a command reference
+  generated from the CLI manifest.
+- Machine-readable docs for AI agents: `llms.txt`, `llms-full.txt`, and
+  `llms-small.txt`.
+- Native tarballs (linux x64/arm64, macOS x64/arm64, Windows x64) attached
+  to every GitHub Release for non-npm installs.
+- Shell completion docs (`pdcli autocomplete bash|zsh|powershell`).
+- `bin/dev.js` development runner (no manifest cache).
+
 ## [0.5.0] - 2026-06-04
 
 ### Added
@@ -85,7 +128,7 @@ All notable changes to `pdcli` are documented here. Format follows
   pagination and `--limit`.
 - Custom-field discovery and resolution: `field list/get` plus automatic
   name/label resolution in table output.
-- Global `search` (itemSearch).
+- Global `search` (itemSearch) and `user me` (v1 users endpoint).
 - Host-locked raw escape hatch: `pdcli api <METHOD> <path>` (v1 + v2).
 - `doctor` diagnostics and `version`.
 - Dual-API client: token-budget-aware 429 backoff, 429→403 hard stop,

package/README.md

@@ -98,6 +98,7 @@ pdcli doctor                             # diagnose auth/keychain/connectivity
 
 - `--output table|json|yaml|csv` everywhere; table in a TTY, JSON when piped.
 - Deterministic [sysexits](https://man.freebsd.org/cgi/man.cgi?query=sysexits) exit codes for scripting.
+- **Docs: [wavyx.github.io/pdcli](https://wavyx.github.io/pdcli)** — guides, cookbook, AI-agent quickstart, [`llms.txt`](https://wavyx.github.io/pdcli/llms.txt).
 - Full reference: [docs/commands.md](docs/commands.md) (generated from the CLI manifest).
 
 ## License

package/bin/dev.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { execute } from '@oclif/core'
+
+const envFile = resolve(process.cwd(), '.env')
+if (existsSync(envFile)) {
+  for (const line of readFileSync(envFile, 'utf8').split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eq = trimmed.indexOf('=')
+    if (eq === -1) continue
+    const key = trimmed.slice(0, eq).trim()
+    const value = trimmed.slice(eq + 1).trim()
+    if (!process.env[key]) process.env[key] = value
+  }
+}
+
+await execute({ dir: import.meta.url })

package/oclif.manifest.json

@@ -5727,14 +5727,14 @@
         "update.js"
       ]
     },
-    "org:create": {
+    "person:create": {
       "aliases": [],
       "args": {},
-      "description": "Create an organization",
+      "description": "Create a person",
       "examples": [
-        "<%= config.bin %> org create --name \"Acme Corp\"",
-        "<%= config.bin %> org create --name \"Tiered\" --field \"Tier=Gold\"",
-        "<%= config.bin %> org create --name \"Raw\" --body '{\"visible_to\":3}'"
+        "<%= config.bin %> person create --name \"Jane Doe\" --email jane@acme.com",
+        "<%= config.bin %> person create --name \"Jane\" --field \"Segment=Enterprise\"",
+        "<%= config.bin %> person create --name \"Raw\" --body '{\"visible_to\":\"3\"}'"
       ],
       "flags": {
         "output": {
@@ -5815,13 +5815,34 @@
           "type": "option"
         },
         "name": {
-          "description": "Organization name",
+          "description": "Person name",
           "name": "name",
           "required": true,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
+        "email": {
+          "description": "Email address (repeatable; first is primary)",
+          "name": "email",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "phone": {
+          "description": "Phone number (repeatable; first is primary)",
+          "name": "phone",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "org": {
+          "description": "Linked organization ID",
+          "name": "org",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "owner": {
           "description": "Owner (user) ID",
           "name": "owner",
@@ -5846,7 +5867,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "org:create",
+      "id": "person:create",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -5856,23 +5877,23 @@
       "relativePath": [
         "src",
         "commands",
-        "org",
+        "person",
         "create.js"
       ]
     },
-    "org:delete": {
+    "person:delete": {
       "aliases": [],
       "args": {
         "id": {
-          "description": "Organization ID",
+          "description": "Person ID",
           "name": "id",
           "required": true
         }
       },
-      "description": "Delete an organization",
+      "description": "Delete a person",
       "examples": [
-        "<%= config.bin %> org delete 7",
-        "<%= config.bin %> org delete 7 --yes"
+        "<%= config.bin %> person delete 42",
+        "<%= config.bin %> person delete 42 --yes"
       ],
       "flags": {
         "output": {
@@ -5962,7 +5983,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "org:delete",
+      "id": "person:delete",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -5972,23 +5993,23 @@
       "relativePath": [
         "src",
         "commands",
-        "org",
+        "person",
         "delete.js"
       ]
     },
-    "org:get": {
+    "person:get": {
       "aliases": [],
       "args": {
         "id": {
-          "description": "Organization ID",
+          "description": "Person ID",
           "name": "id",
           "required": true
         }
       },
-      "description": "Get an organization by ID",
+      "description": "Get a person by ID",
       "examples": [
-        "<%= config.bin %> org get 7",
-        "<%= config.bin %> org get 7 --output json"
+        "<%= config.bin %> person get 5",
+        "<%= config.bin %> person get 5 --output json"
       ],
       "flags": {
         "output": {
@@ -6071,7 +6092,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "org:get",
+      "id": "person:get",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -6081,11 +6102,11 @@
       "relativePath": [
         "src",
         "commands",
-        "org",
+        "person",
         "get.js"
       ]
     },
-    "org:import": {
+    "person:import": {
       "aliases": [],
       "args": {
         "file": {
@@ -6094,10 +6115,10 @@
           "required": true
         }
       },
-      "description": "Bulk-create organizations from a CSV (headers map to fields, custom fields by name)",
+      "description": "Bulk-create persons from a CSV (headers map to fields, custom fields by name)",
       "examples": [
-        "<%= config.bin %> org import orgs.csv",
-        "<%= config.bin %> org import orgs.csv --dry-run"
+        "<%= config.bin %> person import people.csv",
+        "<%= config.bin %> person import people.csv --dry-run"
       ],
       "flags": {
         "output": {
@@ -6193,7 +6214,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "org:import",
+      "id": "person:import",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -6203,17 +6224,17 @@
       "relativePath": [
         "src",
         "commands",
-        "org",
+        "person",
         "import.js"
       ]
     },
-    "org:list": {
+    "person:list": {
       "aliases": [],
       "args": {},
-      "description": "List organizations",
+      "description": "List persons (contacts)",
       "examples": [
-        "<%= config.bin %> org list",
-        "<%= config.bin %> org list --owner 3 --output json"
+        "<%= config.bin %> person list",
+        "<%= config.bin %> person list --org 7 --output json"
       ],
       "flags": {
         "output": {
@@ -6299,11 +6320,18 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "org": {
+          "description": "Filter by organization ID",
+          "name": "org",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "org:list",
+      "id": "person:list",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -6313,24 +6341,24 @@
       "relativePath": [
         "src",
         "commands",
-        "org",
+        "person",
         "list.js"
       ]
     },
-    "org:update": {
+    "person:update": {
       "aliases": [],
       "args": {
         "id": {
-          "description": "Organization ID",
+          "description": "Person ID",
           "name": "id",
           "required": true
         }
       },
-      "description": "Update an organization (v2 PATCH — only provided fields change)",
+      "description": "Update a person (v2 PATCH — only provided fields change)",
       "examples": [
-        "<%= config.bin %> org update 7 --name \"Acme Inc\"",
-        "<%= config.bin %> org update 7 --owner 9",
-        "<%= config.bin %> org update 7 --field \"Tier=Gold\""
+        "<%= config.bin %> person update 42 --name \"New name\"",
+        "<%= config.bin %> person update 42 --email new@acme.com",
+        "<%= config.bin %> person update 42 --field \"Segment=Enterprise\""
       ],
       "flags": {
         "output": {
@@ -6411,12 +6439,33 @@
           "type": "option"
         },
         "name": {
-          "description": "Organization name",
+          "description": "Person name",
           "name": "name",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
+        "email": {
+          "description": "Email address (repeatable; first is primary)",
+          "name": "email",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "phone": {
+          "description": "Phone number (repeatable; first is primary)",
+          "name": "phone",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "org": {
+          "description": "Linked organization ID",
+          "name": "org",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "owner": {
           "description": "Owner (user) ID",
           "name": "owner",
@@ -6441,7 +6490,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "org:update",
+      "id": "person:update",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -6451,18 +6500,18 @@
       "relativePath": [
         "src",
         "commands",
-        "org",
+        "person",
         "update.js"
       ]
     },
-    "person:create": {
+    "org:create": {
       "aliases": [],
       "args": {},
-      "description": "Create a person",
+      "description": "Create an organization",
       "examples": [
-        "<%= config.bin %> person create --name \"Jane Doe\" --email jane@acme.com",
-        "<%= config.bin %> person create --name \"Jane\" --field \"Segment=Enterprise\"",
-        "<%= config.bin %> person create --name \"Raw\" --body '{\"visible_to\":\"3\"}'"
+        "<%= config.bin %> org create --name \"Acme Corp\"",
+        "<%= config.bin %> org create --name \"Tiered\" --field \"Tier=Gold\"",
+        "<%= config.bin %> org create --name \"Raw\" --body '{\"visible_to\":3}'"
       ],
       "flags": {
         "output": {
@@ -6543,34 +6592,13 @@
           "type": "option"
         },
         "name": {
-          "description": "Person name",
+          "description": "Organization name",
           "name": "name",
           "required": true,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "email": {
-          "description": "Email address (repeatable; first is primary)",
-          "name": "email",
-          "hasDynamicHelp": false,
-          "multiple": true,
-          "type": "option"
-        },
-        "phone": {
-          "description": "Phone number (repeatable; first is primary)",
-          "name": "phone",
-          "hasDynamicHelp": false,
-          "multiple": true,
-          "type": "option"
-        },
-        "org": {
-          "description": "Linked organization ID",
-          "name": "org",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
         "owner": {
           "description": "Owner (user) ID",
           "name": "owner",
@@ -6595,7 +6623,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "person:create",
+      "id": "org:create",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -6605,23 +6633,23 @@
       "relativePath": [
         "src",
         "commands",
-        "person",
+        "org",
         "create.js"
       ]
     },
-    "person:delete": {
+    "org:delete": {
       "aliases": [],
       "args": {
         "id": {
-          "description": "Person ID",
+          "description": "Organization ID",
           "name": "id",
           "required": true
         }
       },
-      "description": "Delete a person",
+      "description": "Delete an organization",
       "examples": [
-        "<%= config.bin %> person delete 42",
-        "<%= config.bin %> person delete 42 --yes"
+        "<%= config.bin %> org delete 7",
+        "<%= config.bin %> org delete 7 --yes"
       ],
       "flags": {
         "output": {
@@ -6711,7 +6739,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "person:delete",
+      "id": "org:delete",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -6721,23 +6749,23 @@
       "relativePath": [
         "src",
         "commands",
-        "person",
+        "org",
         "delete.js"
       ]
     },
-    "person:get": {
+    "org:get": {
       "aliases": [],
       "args": {
         "id": {
-          "description": "Person ID",
+          "description": "Organization ID",
           "name": "id",
           "required": true
         }
       },
-      "description": "Get a person by ID",
+      "description": "Get an organization by ID",
       "examples": [
-        "<%= config.bin %> person get 5",
-        "<%= config.bin %> person get 5 --output json"
+        "<%= config.bin %> org get 7",
+        "<%= config.bin %> org get 7 --output json"
       ],
       "flags": {
         "output": {
@@ -6820,7 +6848,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "person:get",
+      "id": "org:get",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -6830,11 +6858,11 @@
       "relativePath": [
         "src",
         "commands",
-        "person",
+        "org",
         "get.js"
       ]
     },
-    "person:import": {
+    "org:import": {
       "aliases": [],
       "args": {
         "file": {
@@ -6843,10 +6871,10 @@
           "required": true
         }
       },
-      "description": "Bulk-create persons from a CSV (headers map to fields, custom fields by name)",
+      "description": "Bulk-create organizations from a CSV (headers map to fields, custom fields by name)",
       "examples": [
-        "<%= config.bin %> person import people.csv",
-        "<%= config.bin %> person import people.csv --dry-run"
+        "<%= config.bin %> org import orgs.csv",
+        "<%= config.bin %> org import orgs.csv --dry-run"
       ],
       "flags": {
         "output": {
@@ -6942,7 +6970,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "person:import",
+      "id": "org:import",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -6952,17 +6980,17 @@
       "relativePath": [
         "src",
         "commands",
-        "person",
+        "org",
         "import.js"
       ]
     },
-    "person:list": {
+    "org:list": {
       "aliases": [],
       "args": {},
-      "description": "List persons (contacts)",
+      "description": "List organizations",
       "examples": [
-        "<%= config.bin %> person list",
-        "<%= config.bin %> person list --org 7 --output json"
+        "<%= config.bin %> org list",
+        "<%= config.bin %> org list --owner 3 --output json"
       ],
       "flags": {
         "output": {
@@ -7048,18 +7076,11 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "org": {
-          "description": "Filter by organization ID",
-          "name": "org",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "person:list",
+      "id": "org:list",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -7069,24 +7090,24 @@
       "relativePath": [
         "src",
         "commands",
-        "person",
+        "org",
         "list.js"
       ]
     },
-    "person:update": {
+    "org:update": {
       "aliases": [],
       "args": {
         "id": {
-          "description": "Person ID",
+          "description": "Organization ID",
           "name": "id",
           "required": true
         }
       },
-      "description": "Update a person (v2 PATCH — only provided fields change)",
+      "description": "Update an organization (v2 PATCH — only provided fields change)",
       "examples": [
-        "<%= config.bin %> person update 42 --name \"New name\"",
-        "<%= config.bin %> person update 42 --email new@acme.com",
-        "<%= config.bin %> person update 42 --field \"Segment=Enterprise\""
+        "<%= config.bin %> org update 7 --name \"Acme Inc\"",
+        "<%= config.bin %> org update 7 --owner 9",
+        "<%= config.bin %> org update 7 --field \"Tier=Gold\""
       ],
       "flags": {
         "output": {
@@ -7167,33 +7188,12 @@
           "type": "option"
         },
         "name": {
-          "description": "Person name",
+          "description": "Organization name",
           "name": "name",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "email": {
-          "description": "Email address (repeatable; first is primary)",
-          "name": "email",
-          "hasDynamicHelp": false,
-          "multiple": true,
-          "type": "option"
-        },
-        "phone": {
-          "description": "Phone number (repeatable; first is primary)",
-          "name": "phone",
-          "hasDynamicHelp": false,
-          "multiple": true,
-          "type": "option"
-        },
-        "org": {
-          "description": "Linked organization ID",
-          "name": "org",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
         "owner": {
           "description": "Owner (user) ID",
           "name": "owner",
@@ -7218,7 +7218,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "person:update",
+      "id": "org:update",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -7228,7 +7228,7 @@
       "relativePath": [
         "src",
         "commands",
-        "person",
+        "org",
         "update.js"
       ]
     },
@@ -9948,5 +9948,5 @@
       ]
     }
   },
-  "version": "0.5.0"
+  "version": "0.7.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavyx/pdcli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },

package/src/base-command.js

@@ -118,9 +118,24 @@ export default class BaseCommand extends Command {
     })
   }
 
-  /** Effective output format: explicit flag, else table in a TTY, json piped. */
+  /** The profile's `default_output` config value, when valid. */
+  storedDefaultOutput() {
+    const stored = loadConfig(this.flags.profile).default_output
+    return ['table', 'json', 'yaml', 'csv'].includes(stored)
+      ? stored
+      : undefined
+  }
+
+  /**
+   * Effective output format: explicit flag, else the profile's
+   * `default_output`, else table in a TTY and json when piped.
+   */
   resolveFormat() {
-    return this.flags.output ?? (process.stdout.isTTY ? 'table' : 'json')
+    return (
+      this.flags.output ??
+      this.storedDefaultOutput() ??
+      (process.stdout.isTTY ? 'table' : 'json')
+    )
   }
 
   /**

package/src/lib/errors.js

@@ -87,7 +87,16 @@ export function handleError(err, cmd) {
   const exitCode = err.exitCode ?? 70
   const flags = cmd.flags ?? {}
 
-  if (flags.output === 'json') {
+  // JSON errors when the user asked for JSON — via the flag or the
+  // profile's default_output. (The piped-TTY fallback intentionally does
+  // NOT apply here; errors stay human unless JSON was requested.)
+  const format =
+    flags.output ??
+    (typeof cmd.storedDefaultOutput === 'function'
+      ? cmd.storedDefaultOutput()
+      : undefined)
+
+  if (format === 'json') {
     const payload = {
       error: err.constructor.name,
       message: err.message,