contextia show

contextia show displays a single Contextia artifact by its ID. It supports progressive disclosure through depth levels and can optionally show code locations that reference the artifact via annotations.

Synopsis

contextia show <id> [OPTIONS]

Arguments

Argument	Description
id	Artifact ID: SPEC-*, NORM-*, DEC-*, or TASK-*

Options

Option	Short	Description
--depth <level>	-d	Detail level: meta, summary, full (default: full)
--implementations	-i	Show @spec and @decision references found in code
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json
--help	-h	Show help and exit

Depth levels

The --depth option controls how much of the artifact is displayed, supporting progressive disclosure:

meta — Frontmatter fields only. Useful for quick lookups and index-building.

$ contextia show SPEC-AUTH-001 --depth meta
SPEC-AUTH-001: Authentication Flow
  status:  approved
  paths:   src/auth/**, src/middleware/auth.py
  links:   DEC-002, NORM-SEC-001
  created: 2025-11-15

summary — Frontmatter plus the first section of the document body.

$ contextia show SPEC-AUTH-001 --depth summary
SPEC-AUTH-001: Authentication Flow
  status:  approved
  paths:   src/auth/**, src/middleware/auth.py
  links:   DEC-002, NORM-SEC-001

## Overview
Users authenticate via OAuth 2.0 with PKCE. The auth module handles
token issuance, refresh, and revocation. All protected endpoints
require a valid access token in the Authorization header.

full (default) — The entire document including all sections.

Implementations flag

The --implementations flag triggers a scan of the codebase for annotation references to the given artifact:

$ contextia show SPEC-AUTH-001 --implementations
SPEC-AUTH-001: Authentication Flow
  status: approved

## Implementations
  src/auth/oauth.py:12       # @spec SPEC-AUTH-001 – OAuth client setup
  src/auth/tokens.py:45      # @spec SPEC-AUTH-001 – Token validation
  src/middleware/auth.py:8    # @spec SPEC-AUTH-001 – Auth middleware
  tests/test_auth.py:3       # @test SPEC-AUTH-001 – Auth test suite

This reads the annotations.prefix and comment_syntax settings from config.yaml to locate annotations across all configured languages.

Examples

Show a decision record:

$ contextia show DEC-002
DEC-002: OAuth 2.0 with PKCE over API keys
  status:    accepted
  specs:     SPEC-AUTH-001
  created:   2025-10-20

## Context
We need an authentication mechanism for the public API...

## Decision
Use OAuth 2.0 with PKCE for all client authentication...

## Consequences
- Token refresh adds complexity to client implementations
- PKCE eliminates the need for client secrets in SPAs

Show a norm in JSON format:

$ contextia show NORM-SEC-001 --json
{
  "id": "NORM-SEC-001",
  "title": "No secrets in source code",
  "scope": "**/*",
  "enforcement": "error",
  "body": "All secrets must be loaded from environment variables..."
}

Show a task at meta depth:

$ contextia show TASK-007 --depth meta
TASK-007: Implement OAuth login
  kind:    feature
  status:  active
  specs:   SPEC-AUTH-001
  created: 2026-02-28

Context format for LLM consumption:

$ contextia show SPEC-AUTH-001 --format context
[SPEC-AUTH-001] Authentication Flow (approved)
paths: src/auth/**, src/middleware/auth.py
links: DEC-002, NORM-SEC-001
---
Users authenticate via OAuth 2.0 with PKCE. The auth module handles
token issuance, refresh, and revocation.

Behavior

• If the ID does not match any artifact, the command exits with code 1 and prints an error to stderr.
• The --implementations flag requires a code scan and may be slower on large codebases. Results are cached in .contextia/.cache/ after the first run.
• The --depth flag has no effect when --json is used; JSON output always includes all fields.