jml 7d58465e62 docs(aphoria): update CLI reference with bulk import features

Add documentation for:
- --template flag (generate example TOML)
- --validate-only flag (check without importing)
- --format flag (table|json output)
- Validation details (what gets checked)
- Link to comprehensive bulk import guide

All examples tested and working.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-02-10 05:35:03 +00:00

21 KiB

Raw Blame History

Aphoria CLI Reference

Complete reference for all Aphoria commands.

Core Commands

`aphoria scan`

Scan codebase for conflicts with authoritative sources.

# Quick ephemeral scan (fast, ~0.25s)
aphoria scan .

# Persistent scan (enables drift detection)
aphoria scan --persist

# With sync (enables community learning)
aphoria scan --persist --sync

# CI mode (exit code 1 on BLOCK)
aphoria scan --exit-code

# Pre-commit (staged files only)
aphoria scan --staged --exit-code

# Output formats
aphoria scan --format table      # Human-readable (default)
aphoria scan --format json       # Machine-readable
aphoria scan --format sarif      # GitHub Security tab
aphoria scan --format markdown   # Documentation

Options:

--persist - Use persistent mode with Episteme storage (enables drift detection)
--sync - Enable community learning: observations feed back into pattern aggregates (requires --persist)
--exit-code - Exit with code 1 if BLOCK verdicts found
--staged - Only scan git staged files
--format <FORMAT> - Output format: table, json, sarif, markdown
--show-observations - Include all observations in output (not just conflicts)

Community Learning: When --sync is enabled, observations from your scan are aggregated into community pattern records. Patterns with 95%+ adoption + authority backing auto-promote to the corpus.

Note: Aphoria respects exclusion patterns from .aphoriaignore and aphoria.toml, plus inline ignore comments. See Ignoring Files and Findings below.

`aphoria init`

Initialize Aphoria in current directory.

aphoria init

Creates .aphoria/ directory with:

claims.toml - Human-authored claims
pending-markers.toml - Inline claim markers (if any)
config.toml - Project configuration
db/ - Project database (per-project observations)

Note: Corpus is no longer hardcoded. It's emergent from community patterns (see aphoria corpus commands) or imported from external sources (wiki, Trust Packs).

Database Architecture:

Per-project database: .aphoria/db/ (observations from this project)
Shared corpus database: ~/.aphoria/corpus-db/ (aggregated patterns across all projects)

See configuration.md for database path customization.

`aphoria ack`

Acknowledge a conflict as intentional.

aphoria ack "code://python/requests/tls/cert_verification" \
  --reason "Local dev environment with self-signed certs"

`aphoria bless`

Define a pattern as your authoritative standard.

aphoria bless "code://rust/crypto/algorithm" \
  --value "ChaCha20Poly1305" \
  --reason "Org standard cipher suite"

Claims Management

`aphoria claims create`

Create a new human-authored claim.

aphoria claims create \
  --id wallet-seqcst-001 \
  --concept-path maxwell/core/wallet/atomics/ordering \
  --predicate pattern \
  --value SeqCst \
  --comparison equals \
  --provenance "Security analysis: wallet atomics prevent double-spend" \
  --invariant "All wallet atomic operations MUST use SeqCst" \
  --consequence "Weakening to Relaxed creates race conditions" \
  --tier expert \
  --evidence "wallet.rs lock-free design" \
  --evidence "Rust Atomics and Locks Ch. 3" \
  --category safety \
  --by jml

Required:

--id - Unique claim ID (e.g., "wallet-seqcst-001")
--concept-path - Concept path (e.g., "project/module/concept")
--predicate - Predicate (e.g., "pattern", "imported", "value")
--value - Value to check (parsed as bool, number, or text)
--provenance - Where this claim came from
--invariant - What must stay true
--consequence - What breaks if violated
--tier - Authority tier: regulatory, clinical, observational, expert, community, anecdotal
--category - Category: safety, architecture, imports, constants, derives, etc.
--by - Author name

Optional:

--comparison - Comparison mode (default: equals)
- equals - Exact match
- not_equals - Must not equal
- present - Must exist
- absent - Must not exist
- contains - Must contain substring/list element
- not_contains - Must NOT contain substring/list element
--evidence - Supporting evidence (can specify multiple times)

See comparison-modes.md for detailed comparison mode guide.

Note: When claims are ingested, Aphoria automatically captures the current git commit hash (if in a git repository) and stores it in the assertion metadata. This provides temporal context linking claims to specific code versions without requiring manual tracking.

`aphoria claims list`

List all claims.

# List all claims
aphoria claims list

# Filter by category
aphoria claims list --category safety

# Filter by status
aphoria claims list --status active
aphoria claims list --status deprecated

# JSON output
aphoria claims list --format json

`aphoria claims explain`

Generate detailed explanation for claims.

# Explain all claims (markdown)
aphoria claims explain

# Explain specific claim
aphoria claims explain --claim wallet-seqcst-001

# Output to file
aphoria claims explain -o claims-explained.md

# JSON format
aphoria claims explain --format json

Creates a document with:

Claim ID and metadata
Provenance (where it came from)
Invariant (what must stay true)
Consequence (what breaks if violated)
Evidence chain
Authority tier

`aphoria claims update`

Update fields on an existing claim.

aphoria claims update wallet-seqcst-001 \
  --invariant "Updated invariant text" \
  --consequence "Updated consequence" \
  --tier regulatory

Options:

--provenance - Update provenance
--invariant - Update invariant
--consequence - Update consequence
--tier - Update authority tier
--evidence - Add evidence (can specify multiple)
--category - Update category
--value - Update value

`aphoria claims supersede`

Mark a claim as superseded by a new claim.

aphoria claims supersede wallet-seqcst-001 \
  --new-id wallet-seqcst-002 \
  --value AcqRel \
  --provenance "Updated after performance analysis" \
  --invariant "Relaxed to AcqRel for perf" \
  --consequence "Still safe for single-writer" \
  --tier expert \
  --by jml

Creates a new claim and marks the old one as superseded.

`aphoria claims deprecate`

Mark a claim as deprecated.

aphoria claims deprecate wallet-seqcst-001 \
  --reason "No longer relevant after refactor"

Deprecated claims are not verified but remain in the file for audit trail.

`aphoria claims import`

Import claims in batch from a TOML file with validation, reporting, and merge strategies.

# Generate template
aphoria claims import --template > my-claims.toml

# Validate without importing
aphoria claims import my-claims.toml --validate-only

# Preview import (dry-run)
aphoria claims import docs/guidelines.toml --dry-run

# Import with JSON output (for tooling)
aphoria claims import docs/guidelines.toml --format json

# Import with TeamPolicy tier
aphoria claims import docs/guidelines.toml \
  --authority-tier team_policy \
  --source-guide "hexagonal-arch"

# Import with merge strategy
aphoria claims import docs/guidelines.toml \
  --merge overwrite                    # Overwrite existing claims
aphoria claims import docs/guidelines.toml \
  --merge skip_existing                # Skip duplicates (default)
aphoria claims import docs/guidelines.toml \
  --merge fail_on_duplicate            # Fail if duplicate found

Options:

--template - Generate example TOML template (omit FILE to use this)
--validate-only - Check file format without importing
--format <FORMAT> - Output format: table (default, human-readable) or json (tooling integration)
--authority-tier <TIER> - Override authority tier for all imported claims (team_policy, expert, etc.)
--source-guide <NAME> - Track the guideline name for compliance filtering (stored in .aphoria/ingested_guides.toml)
--dry-run - Preview changes without writing to file
--merge <STRATEGY> - Merge strategy: skip_existing (default), overwrite, fail_on_duplicate

Validation:

Pre-import validation catches errors before any writes:

Invalid claim IDs (must be kebab-case: lowercase, hyphens only)
Unknown authority tiers
Empty required fields (provenance, invariant, consequence, category, created_by)
Duplicate IDs within import file
Duplicate concept_path+predicate combinations (warnings)

All errors are reported at once with clear context (claim index, ID, field, error message).

See also: Bulk Import Guide for complete documentation and examples.

TOML Format:

[[claim]]
id = "hex-arch-http-001"
concept_path = "myapp/adapters/http"
predicate = "layer"
value = "adapter"
comparison = "equals"
provenance = "Hexagonal Architecture Guidelines"
invariant = "HTTP handlers MUST be in adapters layer"
consequence = "Business logic leaks into infrastructure"
authority_tier = "team_policy"
category = "architecture"
evidence = ["docs/architecture/hexagonal.md"]
created_by = "architecture-team"
created_at = "2026-02-08T12:00:00Z"

[[claim]]
id = "hex-arch-domain-imports-001"
concept_path = "myapp/domain/imports"
predicate = "imported"
value = "http"
comparison = "absent"
provenance = "Hexagonal Architecture Guidelines"
invariant = "Domain layer MUST NOT import HTTP adapters"
consequence = "Circular dependency breaks architecture"
authority_tier = "team_policy"
category = "architecture"
evidence = ["docs/architecture/hexagonal.md"]
created_by = "architecture-team"
created_at = "2026-02-08T12:00:00Z"

Guideline Tracking:

When you use --source-guide, Aphoria tracks the guideline in .aphoria/ingested_guides.toml:

[[guide]]
id = "hexagonal-arch"
name = "hexagonal-arch"
source_path = "docs/guidelines.toml"
document_hash = "blake3:abc123..."
ingested_at = "2026-02-08T12:00:00Z"
claims_count = 26
authority_tier = "team_policy"
category = "imported"
claim_ids = ["hex-arch-http-001", "hex-arch-domain-imports-001", ...]

This enables:

Change detection (hash comparison)
Compliance filtering (future: aphoria scan --check-policy hexagonal-arch)
Audit trail (who imported what, when)

Inline Claim Markers

`aphoria claims list-markers`

List pending inline claim markers.

# List all markers
aphoria claims list-markers

# Filter by status
aphoria claims list-markers --status pending
aphoria claims list-markers --status formalized
aphoria claims list-markers --status rejected

# JSON output
aphoria claims list-markers --format json

Inline markers are special comments in code:

// @aphoria:claim[safety] Wallet MUST NOT derive Clone
#[derive(Debug)]
pub struct Wallet { ... }

`aphoria claims formalize-marker`

Convert an inline marker into a full claim.

aphoria claims formalize-marker marker-001 \
  --id wallet-no-clone-001 \
  --tier expert \
  --evidence "Wallet contains AtomicU64" \
  --by jml

This:

Creates a full claim in claims.toml
Marks the inline marker as formalized
Links the marker to the claim ID

After formalizing, update the comment:

// @aphoria:claimed wallet-no-clone-001
#[derive(Debug)]
pub struct Wallet { ... }

`aphoria claims reject-marker`

Reject an inline marker.

aphoria claims reject-marker marker-001 \
  --reason "False positive - this Clone is safe"

Marks the inline marker as rejected so it won't be suggested again.

Verification Engine

`aphoria verify run`

Verify all authored claims against current codebase.

# Verify all claims
aphoria verify run

# Verify specific claims
aphoria verify run wallet-seqcst-001 wallet-no-clone-001

# Filter by category
aphoria verify run --category safety

# Output formats
aphoria verify run --format table
aphoria verify run --format json
aphoria verify run --format markdown

Verdicts:

PASS - Claim matches observations (green)
CONFLICT - Claim contradicts observations (red)
MISSING - No observations found for this claim (yellow)

Matching Capabilities:

Path Matching - Respects crate boundaries and module hierarchies
Predicate Filtering - Prevents cross-predicate matches (imports vs derives)
Value-Specific Checks - "absent" mode checks for specific forbidden values
Wildcard Patterns - Supports patterns like message/*/derives for flexible matching
Comparison Modes - Six modes: equals, not_equals, present, absent, contains, not_contains

Example output:

PASS     wallet-seqcst-001 | maxwell/core/wallet/atomics/ordering/pattern = SeqCst
         Matched: core/src/wallet.rs:62 (confidence 1.0)

CONFLICT wallet-no-clone-001 | maxwell/core/wallet/type/wallet/derives/traits = Clone
         Found: core/src/wallet.rs:28 (traits = Text("Clone,Debug"))
         Consequence: Clone on Wallet allows multiple instances...

Claims: 10 total | 9 pass | 1 conflict | 0 missing

`aphoria verify map`

Show which extractors can verify which claims.

aphoria verify map

Outputs a table showing:

Claim ID
Covering extractors (which extractors can verify this claim)
Status (✓ covered, ✗ uncovered)

Example:

Claim ID                    | Covering Extractors           | Status
----------------------------|-------------------------------|--------
wallet-seqcst-001          | atomic_ordering               | ✓
wallet-no-clone-001        | derive_pattern                | ✓
core-no-tokio-001          | import_graph                  | ✓
tls-cert-verification-001  | tls_verify, config_security   | ✓
unclaimed-concept-001      |                               | ✗

Use this to identify:

Claims that lack extractor support (need new extractors)
Claims covered by multiple extractors (redundancy)
Coverage gaps in verification

Policy Management

`aphoria policy export`

Export standards as a Trust Pack.

aphoria policy export trust-pack.json

`aphoria policy import`

Import a Trust Pack from security team.

aphoria policy import trust-pack.json

Governance (Enterprise)

`aphoria governance pending`

List approval requests (Phase 14).

aphoria governance pending

Corpus Management

`aphoria corpus build`

Build authoritative corpus from configured sources.

aphoria corpus build
aphoria corpus build --offline  # Skip network sources (RFC, OWASP)
aphoria corpus build --only hardcoded,vendor

Note: Corpus is now community-driven. This command builds from:

Community patterns (StemeDB pattern aggregates)
RFC/OWASP (if enabled)
Imported sources (wiki, Trust Packs)

`aphoria corpus import`

Import best practices from external sources.

# Import from wiki markdown files
aphoria corpus import --from-wiki ~/docs/wiki/content

# Import from JSON
aphoria corpus import --from-json assertions.json

Parses markdown for MUST/SHOULD patterns, creates assertions, stores in StemeDB.

`aphoria corpus list`

List available corpus sources.

aphoria corpus list

Audit Trail

`aphoria audit export`

Export audit trail for SOC 2 compliance.

aphoria audit export --since 2026-01-01

Configuration

Project Config (`.aphoria/config.toml`)

[project]
name = "maxwell"
description = "Compute daemon with entropy accounting"

[episteme]
wal_dir = ".aphoria/wal"
store_dir = ".aphoria/store"
signing_key_path = ".aphoria/signing.key"

[thresholds]
block_threshold = 0.85
flag_threshold = 0.70

Environment Variables

APHORIA_CONFIG - Path to config file (default: .aphoria/config.toml)
APHORIA_LOG - Log level: trace, debug, info, warn, error
APHORIA_HOSTED_URL - Hosted corpus URL (for --sync)

Exit Codes

0 - Success (no BLOCK verdicts or all claims passed)
1 - Failure (BLOCK verdicts found or claim conflicts)
3 - Configuration error

Git Integration

Aphoria automatically integrates with git repositories to provide temporal context for claims and observations.

Automatic Commit Hash Tracking

When claims or observations are ingested into Episteme, Aphoria automatically captures the current git commit hash:

{
  "authored": true,
  "git_commit": "de7af7c1b9e7f6a5d4c3b2a1098765432100abcd",
  "claim_id": "wallet-no-clone-001",
  "provenance": "Wallet is singleton with atomic state",
  "invariant": "Wallet type MUST NOT derive Clone"
}

Benefits:

Temporal Context - Know exactly which code version a claim was authored against
Audit Trail - Trace architectural decisions through git history
No Manual Tracking - Hash captured automatically at ingestion time
Graceful Degradation - Works seamlessly in non-git environments (hash field simply omitted)

Important: The commit hash is captured when assertions are created, not when TOML files are edited. This avoids the "double-commit problem" where committing a file with a hash in it creates a new commit, invalidating the stored hash.

Staged File Scanning

Scan only git-staged files for pre-commit hooks:

aphoria scan --staged --exit-code

This is faster and more appropriate for pre-commit checks than scanning the entire codebase.

Ignoring Files and Findings

Aphoria provides multiple ways to exclude files and suppress findings to reduce noise and focus on relevant issues.

1. .aphoriaignore File

Create a .aphoriaignore file in your project root using gitignore-style syntax:

# Aphoria Ignore Patterns

# Test fixtures and demo code
tests/fixtures/
examples/

# Third-party code
vendor/
node_modules/

# Glob patterns work too
**/*.test.js
**/test_*.py

Syntax:

One pattern per line
# for comments
* matches any string (e.g., *.test.js)
** matches directories recursively (e.g., **/vendor/)
/ at end matches directories only
Whitespace is trimmed

2. Config File Excludes

Add patterns to .aphoria/config.toml:

[project]
name = "myproject"

[[excludes]]
path = "tests/vulnbank/"
reason = "Intentional vulnerabilities for testing"

[[excludes]]
path = "demo/"
reason = "Demo code with relaxed security"

[[excludes]]
path = "**/fixtures/**"
reason = "Test fixtures"

Glob patterns (*, **) are supported and recommended over legacy prefix matching.

3. Inline Ignore Comments

Suppress specific findings inline:

Single-line ignore:

let password = "test123"; // aphoria:ignore - Test credential

Next-line ignore:

# aphoria:ignore-next-line - Intentional for dev environment
requests.get(url, verify=False)

Block ignore:

// aphoria:ignore-block - Demo authentication
function unsafeAuth() {
  const token = "hardcoded";
  return validateToken(token);
}
// aphoria:end-ignore

Supported comment styles:

// - Rust, Go, C, C++, TypeScript, JavaScript
# - Python, Ruby, Shell, YAML
/* */ - CSS, C-style blocks
-- - SQL
 - HTML, XML

4. Acknowledgments

Formally acknowledge conflicts for audit trails:

aphoria ack "code://python/requests/tls/cert_verification" \
  --reason "Dev environment uses self-signed certificates" \
  --expires 2026-12-31

Acknowledgments are stored in .aphoria/acks.toml and can be version controlled.

Precedence

When multiple ignore mechanisms apply:

Inline ignore comments (highest priority)
.aphoriaignore patterns
Config file excludes
Acknowledgments
Default scan

Best Practices

Version control .aphoriaignore - Team-wide exclusions
Use inline ignores sparingly - Document the "why" in the comment
Acknowledge, don't suppress - Use aphoria ack for intentional violations that need audit trails
Review exclusions regularly - Ensure they're still necessary

Configuration

Aphoria is configured via .aphoria/config.toml in your project root.

Quick example:

[project]
name = "my-project"

[episteme]
data_dir = ".aphoria/db"  # Per-project (default)
corpus_data_dir = "~/.aphoria/corpus-db"  # Shared corpus

[thresholds]
block = 0.7
flag = 0.4

[extractors]
enabled = ["tls_verify", "jwt_config", ...]

For complete configuration reference, see configuration.md.

Key topics:

Database paths (per-project vs shared)
Threshold configuration
Extractor settings
Corpus building options
Community sharing (opt-in)

21 KiB Raw Blame History

Aphoria CLI Reference

Core Commands

aphoria scan

aphoria init

aphoria ack

aphoria bless

Claims Management

aphoria claims create

aphoria claims list

aphoria claims explain

aphoria claims update

aphoria claims supersede

aphoria claims deprecate

aphoria claims import

Inline Claim Markers

aphoria claims list-markers

aphoria claims formalize-marker

aphoria claims reject-marker

Verification Engine

aphoria verify run

aphoria verify map

Policy Management

aphoria policy export

aphoria policy import

Governance (Enterprise)

aphoria governance pending

Corpus Management

aphoria corpus build

aphoria corpus import

aphoria corpus list

Audit Trail

aphoria audit export

Configuration

Project Config (.aphoria/config.toml)

Environment Variables

Exit Codes

Git Integration

Automatic Commit Hash Tracking

Staged File Scanning

Ignoring Files and Findings

1. .aphoriaignore File

2. Config File Excludes

3. Inline Ignore Comments

4. Acknowledgments

Precedence

Best Practices

Configuration

See Also

21 KiB

Raw Blame History

`aphoria scan`

`aphoria init`

`aphoria ack`

`aphoria bless`

`aphoria claims create`

`aphoria claims list`

`aphoria claims explain`

`aphoria claims update`

`aphoria claims supersede`

`aphoria claims deprecate`

`aphoria claims import`

`aphoria claims list-markers`

`aphoria claims formalize-marker`

`aphoria claims reject-marker`

`aphoria verify run`

`aphoria verify map`

`aphoria policy export`

`aphoria policy import`

`aphoria governance pending`

`aphoria corpus build`

`aphoria corpus import`

`aphoria corpus list`

`aphoria audit export`

Project Config (`.aphoria/config.toml`)