docs: comprehensive CLI documentation audit and fixes #31
Conversation
- Fix badge issue flags: level is 1-3 (DV/OV/EV), not 0-4 - Fix badge verify flags: use --offline not --accept-self-signed, remove non-existent --json - Fix key subcommand: 'gen' not 'generate', add actual flags - Add trust command documentation (add/list/remove) - Add badge keep command documentation - Remove '(includes scores)' from JSON output description - Add proper examples with correct flag syntax
There was a problem hiding this comment.
Pull request overview
This PR performs a comprehensive CLI documentation audit, updating command references to match the actual capiscio-core v2.2.0 binary implementation. The changes fix incorrect flag names, add documentation for missing commands, and update examples to be more complete and accurate.
Key changes:
- Replaced non-existent
--accept-self-signedflag with--offlinefor badge verification - Updated badge issue and verify flag descriptions to match actual implementation
- Added documentation for
trustcommand (managing local trust store) andbadge keepcommand (automated badge renewal daemon)
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
docs/reference/commands.md |
Comprehensive update of badge command flags, added trust and badge keep command documentation, updated key command subcommands |
docs/index.md |
Updated badge issue example to include required --sub parameter, simplified validation JSON output description |
README.md |
Updated badge issue and verify examples to use correct flags and include complete parameters |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Clarify --audience flag description - Add examples for badge keep command - Add examples for trust command (add, list, remove) - Fix inconsistent ca.jwk → ca-public.jwk filename - Expand trust level abbreviations (DV, OV, EV) - Fix misleading --self-sign + --level example
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| capiscio badge keep --self-sign --key private.jwk --out badge.jwt | ||
|
|
||
| # Custom renewal timing (renew 2 minutes before expiry, check every 10s) | ||
| capiscio badge keep --self-sign --key private.jwk --renew-before 2m --check-interval 10s | ||
|
|
||
| # With custom expiration | ||
| capiscio badge keep --self-sign --key private.jwk --exp 1h --out /var/run/badge.jwt |
There was a problem hiding this comment.
The badge keep examples all use --self-sign with --key private.jwk, but according to the flags table at line 147, when using --self-sign, additional parameters from badge issue may be required. Specifically, based on the badge issue command documentation above, --sub appears to be required. Consider adding --sub did:web:example.com:agents:my-agent to these examples or clarifying in the flags table whether badge keep has different requirements than badge issue.
| capiscio badge keep --self-sign --key private.jwk --out badge.jwt | |
| # Custom renewal timing (renew 2 minutes before expiry, check every 10s) | |
| capiscio badge keep --self-sign --key private.jwk --renew-before 2m --check-interval 10s | |
| # With custom expiration | |
| capiscio badge keep --self-sign --key private.jwk --exp 1h --out /var/run/badge.jwt | |
| capiscio badge keep --self-sign --key private.jwk --sub did:web:example.com:agents:my-agent --out badge.jwt | |
| # Custom renewal timing (renew 2 minutes before expiry, check every 10s) | |
| capiscio badge keep --self-sign --key private.jwk --sub did:web:example.com:agents:my-agent --renew-before 2m --check-interval 10s | |
| # With custom expiration | |
| capiscio badge keep --self-sign --key private.jwk --sub did:web:example.com:agents:my-agent --exp 1h --out /var/run/badge.jwt |
| - `gen` - Generate a new Ed25519 key pair | ||
|
|
||
| **Example:** | ||
|
|
||
| ```bash | ||
| # Generate a new key pair | ||
| capiscio key gen --out-priv private.jwk --out-pub public.jwk |
There was a problem hiding this comment.
The subcommand name is listed as gen (line 179) for generating keys, but it was previously listed as generate in the old documentation. While this might be correct according to the actual CLI, this represents a breaking change or inconsistency that should be verified. If gen is the correct command, consider mentioning whether generate is still supported as an alias for backward compatibility.
| - `gen` - Generate a new Ed25519 key pair | |
| **Example:** | |
| ```bash | |
| # Generate a new key pair | |
| capiscio key gen --out-priv private.jwk --out-pub public.jwk | |
| - `gen` - Generate a new Ed25519 key pair (previously documented as `generate`) | |
| **Example:** | |
| ```bash | |
| # Generate a new key pair using the current subcommand name | |
| capiscio key gen --out-priv private.jwk --out-pub public.jwk | |
| # In older documentation this subcommand may appear as `generate` | |
| # capiscio key generate --out-priv private.jwk --out-pub public.jwk |
| # Remove a CA key by fingerprint | ||
| capiscio trust remove abc123def456 |
There was a problem hiding this comment.
The fingerprint format in this example (abc123def456) appears to be a placeholder. For better user guidance, consider using a more realistic example fingerprint format that matches what users would actually see from the capiscio trust list command output, or add a note explaining that users should replace this with the actual fingerprint from their trust list.
| # Remove a CA key by fingerprint | |
| capiscio trust remove abc123def456 | |
| # Remove a CA key by fingerprint (use a fingerprint from `capiscio trust list`) | |
| capiscio trust remove 3f5c9a8e2b7d4c1f6a9b0d3e5f7a1c2b4d6e8f0 |
| | `--sub <did>` | Subject DID | | ||
| | `--self-sign` | Issue self-signed badge for development | | ||
| | `--level <1-3>` | Trust level (1=Domain Validation, 2=Organization Validation, 3=Extended Validation) | | ||
| | `--sub <did>` | Subject DID (did:web format) | |
There was a problem hiding this comment.
While the description for --sub correctly states "Subject DID (did:web format)", it might be helpful to add a brief note explaining the format, since users might not be familiar with did:web syntax. For example: "Subject DID (did:web format, e.g., did:web:example.com:agents:my-agent)" or a reference to where users can learn more about did:web identifiers.
| | `--sub <did>` | Subject DID (did:web format) | | |
| | `--sub <did>` | Subject DID (did:web format, e.g., did:web:example.com:agents:my-agent) | |
| | `--exp <duration>` | Expiration duration (default: 5m) | | ||
| | `--key <path>` | Path to private key file | | ||
| | `--domain <string>` | Agent domain | | ||
| | `--iss <url>` | Issuer URL | |
There was a problem hiding this comment.
The flag --iss (Issuer URL) is documented in the flags table but is not demonstrated in any of the examples below. Consider adding an example that shows when and how to use this flag, or clarify in its description when it should be used versus when it's automatically derived.
Summary
Documentation audit verifying CLI examples against actual
capiscio v2.2.0binary.Issues Fixed
--accept-self-signedflag--offlinetrustcommandsbadge keepFiles Changed
README.md: Fixed badge issue/verify flags, added trust commandsdocs/index.md: Fixed badge issue/verify flagsdocs/reference/commands.md: Comprehensive update of all badge flags, added trust and badge keepVerification
All changes verified against
capiscio-core v2.2.0 --helpoutput.Audit date: 2025-12-26