Improve CLI human output base

AGENTS.md

@@ -7,20 +7,20 @@ This repository ships a CLI-first interface for agents. Do not rely on MCP, brow
 Run these first:
 
 ```bash
-pcl --llms
-pcl doctor
-pcl auth ensure --format toon
-pcl whoami
-pcl api manifest --format toon
+pcl --toon --llms
+pcl doctor --toon
+pcl auth ensure --toon
+pcl whoami --toon
+pcl api manifest --toon
 ```
 
 When changing this repository, run `make ci` before handing work back. It sets `PCL_AUTH_NO_BROWSER=1` for tests so auth flows do not open a browser, and it runs `make agent-smoke` to verify the documented agent discovery path.
 
-Use TOON as the normal machine interface; it is the default compact envelope and is cheaper for agents to consume. Examples in this file prefer default TOON or `--format toon` when the contract should be explicit. Use `--json` or `--format json` only when a downstream tool needs strict JSON.
+Use TOON as the normal machine interface. Default CLI output is optimized for humans, so agent examples must pass `--toon`. Use `--json` only when a downstream tool needs strict JSON.
 
 ## Output Contract
 
-Every agent-facing command should be treated as an envelope. In default TOON this is shaped like:
+Every agent-facing command should be treated as an envelope. With `--toon` this is shaped like:
 
 ```toon
 status: ok
@@ -34,9 +34,9 @@ Errors use the same shape with `status: "error"` and an `error` object. Do not p
 
 Output mode rules:
 
-- default: TOON envelope
-- explicit TOON: `--format toon`
-- JSON: `--json` or `--format json`
+- default: human-readable output for people
+- TOON: `--toon`
+- JSON: `--json`
 - JSONL exception: fresh `pcl auth login --json` streams events and marks the final event with `terminal: true`
 
 Fresh `pcl auth login --json` emits JSONL progress events: first `event: auth.login_instructions`, then a terminal envelope with `terminal: true`. Treat only the terminal event as the final login result. Existing valid auth still returns a single JSON envelope.
@@ -45,9 +45,9 @@ Fresh `pcl auth login --json` emits JSONL progress events: first `event: auth.lo
 
 Prefer the surfaces in this order:
 
-1. `pcl --llms` or `pcl llms` for the current agent guide.
-2. `pcl workflows` for task recipes.
-3. `pcl schema list` and `pcl schema get <workflow> --action <action>` for workflow action contracts.
+1. `pcl --toon --llms` or `pcl llms --toon` for the current agent guide.
+2. `pcl workflows --toon` for task recipes.
+3. `pcl schema list --toon` and `pcl schema get <workflow> --action <action> --toon` for workflow action contracts.
 4. Top-level workflow commands like `pcl incidents`, `pcl projects`, `pcl assertions`, `pcl account`, `pcl releases`, and `pcl protocol-manager`.
 5. `pcl api list`, `pcl api inspect`, `pcl api call`, and `pcl api coverage` only for debugging, API parity checks, internal/service endpoints, or endpoints without `workflow_alternatives`.
 
@@ -70,19 +70,19 @@ Raw calls are not the normal product path. Use them for debugging, API parity ch
 Both query forms are valid:
 
 ```bash
-pcl api call get '/views/public/incidents?limit=5' --allow-unauthenticated --format toon
-pcl api call get /views/public/incidents --query limit=5 --allow-unauthenticated --format toon
+pcl api call get '/views/public/incidents?limit=5' --allow-unauthenticated --toon
+pcl api call get /views/public/incidents --query limit=5 --allow-unauthenticated --toon
 ```
 
 For simple raw request bodies, `pcl api call` accepts repeated `--field key=value` and merges those fields into a JSON object, matching workflow command behavior. Use `--body-file` for nested payloads.
 
-Use `pcl api inspect <operation-id> --format toon` before calling unfamiliar endpoints. Inspect includes `workflow_alternatives`, `raw_api_use`, auth metadata, and required header placeholders; preserve required `--header` values in generated examples. For required request bodies, inspect the operation and prefer `--body-file`.
+Use `pcl api inspect <operation-id> --toon` before calling unfamiliar endpoints. Inspect includes `workflow_alternatives`, `raw_api_use`, auth metadata, and required header placeholders; preserve required `--header` values in generated examples. For required request bodies, inspect the operation and prefer `--body-file`.
 
 Raw API calls persist `operation_id` in request history when the live OpenAPI manifest can resolve the method/path. After exploratory testing, run:
 
 ```bash
-pcl api coverage --format toon
-pcl api coverage --markdown api-coverage.md --format toon
+pcl api coverage --toon
+pcl api coverage --markdown api-coverage.md --toon
 ```
 
 Use `no_hit`, `no_2xx`, `write_no_2xx`, and `unmatched_records` to decide what still needs manual reconciliation.
@@ -92,11 +92,11 @@ Use `no_hit`, `no_2xx`, `write_no_2xx`, and `unmatched_records` to decide what s
 For investigations, prefer JSONL exports and local job records:
 
 ```bash
-pcl export incidents --project-id <project-id> --environment production --out incidents.jsonl --errors errors.jsonl --checkpoint checkpoint.json --resume --continue-on-error --format toon
-pcl jobs list --format toon
-pcl jobs status <job-id> --format toon
-pcl jobs resume <job-id> --format toon
-pcl artifacts list --format toon
+pcl export incidents --project-id <project-id> --environment production --out incidents.jsonl --errors errors.jsonl --checkpoint checkpoint.json --resume --continue-on-error --toon
+pcl jobs list --toon
+pcl jobs status <job-id> --toon
+pcl jobs resume <job-id> --toon
+pcl artifacts list --toon
 ```
 
 Export commands record `job_id`, `resume_command`, checkpoint path, output path, and error path. Use those fields instead of rebuilding pagination state manually.
@@ -106,16 +106,16 @@ Export commands record `job_id`, `resume_command`, checkpoint path, output path,
 Use:
 
 ```bash
-pcl auth status --format toon
-pcl auth ensure --format toon
-pcl whoami --format toon
+pcl auth status --toon
+pcl auth ensure --toon
+pcl whoami --toon
 ```
 
-Do not treat a stored token as valid unless `token_valid` is true and `expired` is false. `pcl doctor --format toon` also checks whether the target API advertises CLI login, refresh, and remote logout/revocation endpoints. Public endpoints should be called with `--allow-unauthenticated` when using raw `pcl api call`.
+Do not treat a stored token as valid unless `token_valid` is true and `expired` is false. `pcl doctor --toon` also checks whether the target API advertises CLI login, refresh, and remote logout/revocation endpoints. Public endpoints should be called with `--allow-unauthenticated` when using raw `pcl api call`.
 
-Use `pcl auth ensure --format toon` before long workflows. It returns `status: ok` when auth is usable, or one `status: action_required` envelope with `device_url`, `code`, `device_secret`, and `poll_command` when user login is needed. Run `poll_command` until it returns `status: ok` or `status: error`.
+Use `pcl auth ensure --toon` before long workflows. It returns `status: ok` when auth is usable, or one `status: action_required` envelope with `device_url`, `code`, `device_secret`, and `poll_command` when user login is needed. Run `poll_command` until it returns `status: ok` or `status: error`.
 
-`expires_soon: true` means the access token has five minutes or less remaining. `pcl auth refresh --format toon` is safe to call and rotates the stored CLI refresh token when available; if the refresh token is missing or rejected, it returns the same login challenge shape. `pcl auth login --no-wait --format toon` also returns a single challenge envelope. Use `pcl auth login --json` only when you specifically want the JSONL streaming login contract. `pcl auth logout` attempts remote logout first, then clears local credentials; use `pcl auth logout --local` only when you explicitly want local cleanup.
+`expires_soon: true` means the access token has five minutes or less remaining. `pcl auth refresh --toon` is safe to call and rotates the stored CLI refresh token when available; if the refresh token is missing or rejected, it returns the same login challenge shape. `pcl auth login --no-wait --toon` also returns a single challenge envelope. Use `pcl auth login --json` only when you specifically want the JSONL streaming login contract. `pcl auth logout` attempts remote logout first, then clears local credentials; use `pcl auth logout --local` only when you explicitly want local cleanup.
 
 Auth commands use `--auth-url`/`PCL_AUTH_URL` when set, otherwise they follow `PCL_API_URL` before falling back to the production app URL.
 
@@ -127,7 +127,7 @@ When reporting results, preserve:
 - Incident IDs, transaction hashes, trace IDs, project IDs, and artifact paths.
 - The exact command used, especially for exports and mutations.
 
-Use `pcl requests list --format toon` to recover recent request metadata.
+Use `pcl requests list --toon` to recover recent request metadata.
 
 ## Shell Completions
 
@@ -139,4 +139,4 @@ pcl completions zsh
 pcl completions fish
 ```
 
-Use `--format json` for completions only when a downstream installer expects the script inside a JSON envelope.
+Use `--json` for completions only when a downstream installer expects the script inside a JSON envelope.

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable user-facing changes should be recorded here.
 
 ## Unreleased
 
+## 1.4.3 - 2026-05-10
+
+- Made default CLI output human-first across command surfaces, including auth, config, workflow, schema, API discovery, dry-run, export, job, artifact, request log, collection, incident, and raw API response views.
+- Added `--toon` as the compact agent-readable output mode while preserving `--json` and hidden legacy `--format` compatibility.
+- Updated agent-facing docs and smoke checks to use `--toon`.
+
 ## 1.4.2 - 2026-05-09
 
 - Updated Credible SDK assertion dependencies to the latest 1.4 assertion runtime graph.

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "1.4.2"
+version = "1.4.3"
 edition = "2024"
 authors = ["Phylax Systems"]
 license = "BSL 1.1"