CLI Overview

The Contextia CLI (contextia) is the human-facing interface for managing context architecture in your project. It shares the same core logic as the MCP server, so every operation you perform via the CLI produces identical results to what an AI agent sees through the MCP tools.

Installation

# Install with uv (recommended)
uv tool install contextia

# Or run directly without installing
uvx contextia --help

Synopsis

contextia [OPTIONS] COMMAND [ARGS]

Global options

Option	Short	Description
--format <fmt>	-f	Output format: human (default), json, context
--json	-j	Shorthand for --format json
--no-color		Disable colored output (also respects NO_COLOR env var)
--root <path>	-r	Override project root (default: auto-detected)
--verbose	-v	Print additional diagnostic information to stderr
--help	-h	Show help and exit
--version		Show version and exit

Output formats

Every command supports three output formats, controlled by --format:

human (default) — Colored, tabular output designed for terminal use.

$ 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

json — Machine-parseable JSON, suitable for piping to jq or other tools.

$ contextia list --type spec --json | jq '.[].id'
"SPEC-AUTH-001"
"SPEC-API-002"
"SPEC-DB-003"

context — Compact, ANSI-free output optimized for LLM consumption. Used internally by the MCP server.

$ 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...

Project root discovery

Contextia locates your project root by walking up from the current working directory, searching for .contextia/config.yaml. This is the same mechanism used by git to find .git/:

/home/user/project/src/auth/   # you are here
/home/user/project/src/        # no .contextia/config.yaml
/home/user/project/            # .contextia/config.yaml found -> project root

You can override this with --root:

contextia --root /path/to/project list --type spec

CLI and MCP: two interfaces, one core

The CLI and MCP server are thin wrappers around the same core library. The core functions know nothing about output formatting or transport:

CLI (cyclopts)  ->  core.find_specs(root, query=...)  ->  format for terminal
MCP (FastMCP)   ->  core.find_specs(root, query=...)  ->  format for agent

This means every bug fix or feature added to the core is automatically available in both interfaces. The CLI is for humans running commands in a terminal; the MCP server is for AI agents calling tools programmatically.

Commands

Command	Description
init	Create a new .contextia/ directory
new	Scaffold a new artifact (spec, task, decision, norm)
show	Display a single artifact by ID
search	Free-text search across artifacts
list	List all artifacts with filtering
trace	Reverse lookup: file path to governing specs/norms
context	Assemble full context for a task
check	Validate integrity of the context architecture
task	Manage task lifecycle
log	Read and write session logs

Environment variables

Variable	Description
NO_COLOR	Disable colored output (any value)
CONTEXTIA_ROOT	Override project root discovery
CONTEXTIA_FORMAT	Default output format (human, json, context)

Exit codes

Code	Meaning
0	Success
1	Error (broken refs, missing files, invalid input)
2	Usage error (invalid arguments)