Skip to main content
The colin run command compiles your project. It discovers documents in your models/ directory, resolves dependencies between them, and produces compiled output in output/. During compilation, Colin invokes LLM calls as needed, caches their results, and tracks changes to enable incremental rebuilds. A compilation run involves several phases: discovery finds all documents, graph building extracts dependency edges from ref() calls, topological sorting determines compilation order, and finally each document compiles with its dependencies already available.

​
Basic Usage

From your project directory, run: 
colin run
Colin displays progress as it compiles, showing each document and its operations: 
Config:  colin.toml
Project: my-context
Output:  output/

✓ company.md
✓ products/overview.md
  ✓ ref:company
✓ skills/product-expert.md
  ✓ ref:products/overview
  ✓ llm:auto:a3f2c1
The output shows which documents were compiled and what operations occurred within each.

​
Reading the Output

Colin’s display uses icons to indicate operation status and type:
IconMeaning
✓Compiled successfully
»Served from cache
←Reference or MCP fetch
→File output written
✗Failed
When you see » for an LLM operation, Colin reused a cached result from a previous run. This happens when the input to the LLM call hasn’t changed. The ← icon indicates a reference was resolved, either from another document or an MCP resource. A typical run where some documents were cached: 
✓ context/team-health.md
  ← ref:sources/linear
  » llm:auto:b7e4d2
  ← mcp:github
✓ skills/status-agent.md
  ← ref:context/team-health
  ✓ llm:auto:c8f5e3
Here, context/team-health.md had a cached LLM result, while skills/status-agent.md made a fresh LLM call.

​
Flags

​
No Cache

The --no-cache flag ignores cached results and recompiles everything: 
colin run --no-cache
Use this when you want fresh LLM outputs regardless of whether inputs changed. This discards the manifest and starts from scratch, so all LLM calls execute again.

​
Quiet Mode

The -q or --quiet flag suppresses progress output: 
colin run -q
In quiet mode, Colin only outputs errors. Use this in scripts or CI environments where you only care about success or failure.

​
Output Override

The --output flag overrides the output directory from colin.toml: 
colin run --output ./output
Compiled documents and the manifest write to the specified directory instead of the default.

​
Ephemeral Mode

The --ephemeral flag prevents Colin from writing to the .colin/ directory: 
colin run --ephemeral
In ephemeral mode, Colin keeps all compiled outputs in memory and writes only to the output/ directory. The manifest and compiled artifacts in .colin/compiled/ are not updated. The run is “ephemeral” in that it leaves no trace in the build system. This is useful for:
  • Testing: Run compilations without leaving state behind
  • CI pipelines: Read-only builds that don’t pollute the cache
  • One-off compilations: Quick runs without persisting manifest or artifacts
  • Templates: Generate output without leaving traces in the source directory
Ephemeral mode can still read from existing cache, benefiting from previously compiled artifacts. To completely ignore the cache, combine with --no-cache: 
colin run --no-cache --ephemeral
This provides full isolation: no reading from .colin/, no writing to .colin/, but still produces output.
FlagsReads .colin/Writes .colin/Writes output/
(default)✓✓✓
--no-cache✗✓✓
--ephemeral✓✗✓
--no-cache --ephemeral✗✗✓

​
No Clean

By default, Colin removes stale files after compilation. The --no-clean flag skips this: 
colin run --no-clean
Stale files are outputs no longer tracked by the manifest—they appear when you delete or rename model files. Auto-clean removes them without prompting. Use --no-clean when you want to preserve stale files temporarily or when running quick iterations where cleanup isn’t needed.

​
Updating Outputs

The colin update command updates an output directory from its source project: 
# Update a specific output directory
colin update ~/.config/claude/skills

# Or run from within the output directory
cd ~/.config/claude/skills
colin update
Colin reads the manifest, finds the source project, and recompiles. This enables a workflow where skills live in Claude’s folder but compile from a central project elsewhere on your machine. When you compile a project, Colin stores the source project location and any --var overrides in the output manifest. The --update flag uses this information to recompile from the original source. This is useful for:
  • Distributed skills: Update installed skills without tracking their source locations
  • Team workflows: Developers can update outputs in shared locations
The colin update command:
  • Reads .colin-manifest.json from the specified directory (or current directory)
  • Uses stored --var overrides by default (override again with --var)
  • Supports --no-cache, --ephemeral, --quiet, and --no-banner flags
# Force full rebuild during update
colin update --no-cache

# Override a stored variable
colin update --var api_key=new_value

​
Incremental Builds

Colin tracks changes to enable efficient incremental compilation. When you run colin run, it compares each document’s current state against what was recorded in the manifest from the last run. A document recompiles when:
  1. Its source changed - The file content differs from the recorded hash
  2. A dependency changed - Any document it references was recompiled this run
  3. It’s new - No record exists in the manifest
Documents that haven’t changed and whose dependencies are unchanged skip compilation entirely. Their compiled output from the previous run remains in output/.

​
Change Propagation

When a document changes, Colin recompiles all documents that depend on it, transitively. Consider this dependency chain: 
company.md
    ↓
products/overview.md (refs company)
    ↓
skills/support-agent.md (refs products/overview)
If you modify company.md, all three documents recompile because changes propagate downstream through the dependency graph. If you only modify skills/support-agent.md, only that document recompiles since nothing depends on it. The manifest tracks which refs each document evaluated during its last compilation. Colin uses this to trace the downstream closure of affected documents.

​
Compilation Order

Colin compiles documents in topological order based on their dependencies. Documents with no dependencies compile first, then documents whose dependencies are complete, and so on. Within each level of the dependency graph, documents compile in parallel. A project with this structure: 
a.md ─┐
      ├─→ d.md ─→ e.md
b.md ─┤
      │
c.md ─┘
Would compile as:
  1. Level 1: a.md, b.md, c.md (in parallel)
  2. Level 2: d.md
  3. Level 3: e.md
This ordering ensures that when a document compiles, all documents it references are already available.

​
Error Handling

When compilation fails, Colin reports errors clearly: 
Compilation failed

context/analysis.md
├── ✗ LLM call failed: API rate limit exceeded
└── ✗ Template error: Undefined variable 'missing_ref'

skills/agent.md
└── ✗ RefNotCompiledError: ref('nonexistent') failed - document not compiled

2 error(s) in 2 document(s)
Colin attempts to compile as many documents as possible, collecting all errors rather than stopping at the first failure. This gives you the complete picture of what needs fixing. Documents that fail don’t update the manifest, so the next run will attempt them again. Successfully compiled documents are saved normally.