contextia init

contextia init creates the .contextia/ directory structure in the current project, generating the configuration file, identity document, and all required subdirectories.

Synopsis

contextia init [OPTIONS]

Options

Option	Short	Description
--name <name>	-n	Project name (default: auto-detected)
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json
--help	-h	Show help and exit

Project name auto-detection

When --name is not provided, Contextia detects the project name from the first available source:

1. pyproject.toml — reads [project].name
2. package.json — reads name
3. Cargo.toml — reads [package].name
4. .git directory — reads the repository directory name
5. Current directory name as fallback

Generated structure

Running contextia init in a Python project creates:

.contextia/
├── config.yaml
├── system/
│   ├── identity.md
│   ├── specs/
│   ├── norms/
│   └── rationale/
└── work/
    ├── tasks/
    └── logs/

config.yaml

The generated configuration includes auto-detected language settings:

version: "1.0"
project:
  name: my-api
  languages:
    - python

paths:
  system: system
  work: work
  cache: .cache

annotations:
  prefix: "@"
  comment_syntax:
    python: "#"

identity.md

A starter identity document with YAML frontmatter:

---
project: my-api
version: "0.1.0"
---

# my-api

Describe your project here. This document is loaded by AI agents
as always-on context. Keep it concise: what the project is, its
primary purpose, and key architectural choices.

Examples

Initialize with auto-detection:

$ contextia init
Detected project: my-api (from pyproject.toml)
Detected language: python
Created .contextia/config.yaml
Created .contextia/system/identity.md
Created .contextia/system/specs/
Created .contextia/system/norms/
Created .contextia/system/rationale/
Created .contextia/work/tasks/
Created .contextia/work/logs/
Initialized contextia in /home/user/my-api

Initialize with an explicit name:

$ contextia init --name billing-service
Created .contextia/config.yaml
Initialized contextia project: billing-service

JSON output (for scripting):

$ contextia init --json
{
  "project": "my-api",
  "root": "/home/user/my-api",
  "created": [
    ".contextia/config.yaml",
    ".contextia/system/identity.md",
    ".contextia/system/specs/",
    ".contextia/system/norms/",
    ".contextia/system/rationale/",
    ".contextia/work/tasks/",
    ".contextia/work/logs/"
  ]
}

Behavior

• If .contextia/ already exists, the command exits with an error and does not overwrite existing files.
• The command writes status messages to stderr and the result to stdout, allowing clean piping with --json.
• Language detection inspects the presence of pyproject.toml, package.json, Cargo.toml, go.mod, and common file extensions in the project root.

What to do next

After initializing, write your identity.md and create your first spec:

$EDITOR .contextia/system/identity.md
contextia new spec --title "Authentication Flow"