Skip to content

docs: comprehensive CLI documentation audit and fixes #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
beonde merged 3 commits into from
Dec 27, 2025
Merged

docs: comprehensive CLI documentation audit and fixes #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
03395d0
docs: fix CLI command documentation to match actual implementation
beonde Dec 27, 2025
971feae
Merge branch 'main' into docs/comprehensive-audit-2025-12-26
beonde Dec 27, 2025
ccb6736
docs: address copilot review feedback
beonde Dec 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,10 @@ capiscio validate ./agent-card.json
capiscio validate https://my-agent.example.com --json

# Issue a self-signed badge (development)
capiscio badge issue --self-sign
capiscio badge issue --self-sign --sub did:web:example.com:agents:my-agent

# Verify a badge
capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --accept-self-signed
# Verify a badge (offline mode)
capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --offline

# Check version
capiscio --version
Expand Down
4 changes: 2 additions & 2 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,11 +39,11 @@ npm install -g capiscio
# Validate an agent card
capiscio validate ./agent-card.json

# Validate with JSON output (includes scores)
# Validate with JSON output
capiscio validate ./agent-card.json --json

# Issue a self-signed badge (development)
capiscio badge issue --self-sign
capiscio badge issue --self-sign --sub did:web:example.com:agents:my-agent

# Check core version
capiscio --version
Expand Down
111 changes: 92 additions & 19 deletions docs/reference/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,24 +78,26 @@ capiscio badge issue [flags]

| Flag | Description |
|------|-------------|
| `--self-sign` | Issue self-signed badge (Level 0, did:key) |
| `--level <0-4>` | Trust level (0=SS, 1=DV, 2=OV, 3=EV, 4=CV) |
| `--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) |
Copy link

Copilot AI Dec 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
| `--sub <did>` | Subject DID (did:web format) |
| `--sub <did>` | Subject DID (did:web format, e.g., did:web:example.com:agents:my-agent) |

Copilot uses AI. Check for mistakes.
| `--aud <urls>` | Audience (comma-separated URLs) |
| `--exp <duration>` | Expiration duration (default: 5m) |
| `--key <path>` | Path to private key file |
| `--domain <string>` | Agent domain |
| `--iss <url>` | Issuer URL |
Copy link

Copilot AI Dec 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.

**Examples:**

```bash
# Self-signed badge for development
capiscio badge issue --self-sign
capiscio badge issue --self-sign --sub did:web:example.com:agents:my-agent

# With custom expiration
capiscio badge issue --self-sign --exp 1h
# CA-issued badge with specific trust level
capiscio badge issue --level 2 --domain example.com --key ca-private.jwk

# With audience restriction
capiscio badge issue --self-sign --aud "https://api.example.com"
capiscio badge issue --self-sign --aud "https://api.example.com,https://backup.example.com"
```

#### badge verify
Expand All @@ -110,22 +112,56 @@ capiscio badge verify <token> [flags]

| Flag | Description |
|------|-------------|
| `--accept-self-signed` | Accept self-signed badges (Level 0) |
| `--audience <url>` | Verify audience claim |
| `--skip-revocation` | Skip revocation check |
| `--json` | Output as JSON |
| `--key <path>` | Path to public key file (JWK) |
| `--offline` | Offline mode (uses trust store) |
| `--audience <url>` | Expected audience claim value (verifies the badge is intended for this URL) |
| `--skip-revocation` | Skip revocation check (testing only) |
| `--skip-agent-status` | Skip agent status check (testing only) |
| `--trusted-issuers <urls>` | Comma-separated list of trusted issuer URLs |

**Examples:**

```bash
# Verify badge (rejects self-signed by default)
capiscio badge verify "eyJhbGciOiJFZERTQSJ9..."
# Verify badge with CA public key
capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --key ca-public.jwk

# Offline verification (uses local trust store)
capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --offline

# With audience validation
capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --key ca-public.jwk --audience https://api.example.com
```

#### badge keep

# Accept self-signed for development
capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --accept-self-signed
Run a daemon that automatically renews badges before expiry.

# JSON output
capiscio badge verify "eyJhbGciOiJFZERTQSJ9..." --json
```bash
capiscio badge keep [flags]
```

**Flags:**

| Flag | Description |
|------|-------------|
| `--self-sign` | Self-sign instead of requesting from CA |
| `--key <path>` | Path to private key file (required for self-sign) |
| `--out <path>` | Output file path (default: badge.jwt) |
| `--exp <duration>` | Expiration duration (default: 5m) |
| `--renew-before <duration>` | Time before expiry to renew (default: 1m) |
| `--check-interval <duration>` | Interval to check for renewal (default: 30s) |

**Examples:**

```bash
# Run daemon with self-signed badges
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
Comment on lines +158 to +164
Copy link

Copilot AI Dec 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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

Copilot uses AI. Check for mistakes.
```

---
Expand All @@ -140,8 +176,45 @@ capiscio key [command]

**Subcommands:**

- `generate` - Generate a new key pair
- `list` - List stored keys
- `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
Comment on lines +179 to +185
Copy link

Copilot AI Dec 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
- `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

Copilot uses AI. Check for mistakes.
```

---

### trust

Manage the local trust store for offline badge verification.

```bash
capiscio trust [command]
```

**Subcommands:**

- `add` - Add a CA public key to the trust store
- `list` - List trusted CA keys
- `remove` - Remove a CA key from the trust store

**Location:** `~/.capiscio/trust/` (or `$CAPISCIO_TRUST_PATH`)

**Examples:**

```bash
# Add a CA public key to the trust store
capiscio trust add ca-public.jwk

# List all trusted CA keys
capiscio trust list

# Remove a CA key by fingerprint
capiscio trust remove abc123def456
Comment on lines +215 to +216
Copy link

Copilot AI Dec 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
# 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

Copilot uses AI. Check for mistakes.
```

---

Expand Down