contextia list

contextia list displays a catalog of all artifacts in the project. It supports filtering by artifact type and status, with tabular output in human mode and structured data in JSON mode.

Synopsis

contextia list [OPTIONS]

Options

Option	Short	Description
--type <type>	-t	Filter by type: spec, task, decision, norm, all (default: all)
--status <status>	-s	Filter by status (type-dependent, see below)
--sort <field>		Sort by: id, title, created, status (default: id)
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json
--help	-h	Show help and exit

Status values by type

Each artifact type has its own set of valid statuses:

Type	Statuses
spec	draft, approved, deprecated
task	created, active, completed
decision	proposed, accepted, superseded
norm	active, deprecated

Examples

List all artifacts:

$ contextia list
  ID             Type      Title                          Status
  DEC-002        decision  OAuth 2.0 with PKCE            accepted
  DEC-DB-004     decision  Use PostgreSQL over SQLite      accepted
  NORM-SEC-001   norm      No secrets in source code       active
  NORM-TEST-001  norm      Every module has unit tests     active
  SPEC-AUTH-001  spec      Authentication Flow             approved
  SPEC-API-002   spec      REST API Conventions            draft
  SPEC-DB-003    spec      Database Migration Strategy     approved
  TASK-007       task      Implement OAuth login           active
  TASK-012       task      Add rate limiting               created

  9 artifacts found

List only specs:

$ contextia list --type spec
  ID             Title                          Status
  SPEC-AUTH-001  Authentication Flow             approved
  SPEC-API-002   REST API Conventions            draft
  SPEC-DB-003    Database Migration Strategy     approved

  3 specs found

List active tasks:

$ contextia list --type task --status active
  ID        Title                  Kind      Created
  TASK-007  Implement OAuth login  feature   2026-02-28

  1 task found

List approved specs sorted by creation date:

$ contextia list --type spec --status approved --sort created
  ID             Title                          Created
  SPEC-DB-003    Database Migration Strategy     2025-09-10
  SPEC-AUTH-001  Authentication Flow             2025-11-15

JSON output for scripting:

$ contextia list --type norm --json
[
  {
    "id": "NORM-SEC-001",
    "type": "norm",
    "title": "No secrets in source code",
    "scope": "**/*",
    "enforcement": "error",
    "status": "active"
  },
  {
    "id": "NORM-TEST-001",
    "type": "norm",
    "title": "Every module has unit tests",
    "scope": "src/**",
    "enforcement": "warning",
    "status": "active"
  }
]

Context format for agents:

$ contextia list --type spec --format context
[SPEC-AUTH-001] Authentication Flow (approved)
[SPEC-API-002] REST API Conventions (draft)
[SPEC-DB-003] Database Migration Strategy (approved)

Behavior

• Lists are read directly from the .contextia/ directory by scanning frontmatter. No index required.
• When --type is all, results are sorted by ID across all types.
• The --status filter is validated against the allowed statuses for the given type. Using an invalid status prints an error.
• An empty project (no artifacts) prints “No artifacts found” and exits with code 0.