Sigil

CLI tool for querying brand.json data. Local-first, schema-agnostic — works against any brand.json without hardcoded models.

Installation

# Global install
uv tool install .

# Or run from project
uv run --project ~/BRANDS/sigil sigil ...

Quick Start

# From a brand directory (reads local brand.json)
cd ~/BRANDS/digitech
sigil                                    # brand overview
sigil get colors.primary.hex             # → #dfff11
sigil show colors                        # color table with swatches
sigil keys fonts                         # → logo, heading, body, ...

# From a remote brand
sigil get name -s digitech               # → Brad Wenner Digital
sigil show colors -s dungeonchurch       # remote color table

Commands

Command	Description	Default format
sigil	Brand overview	rich
sigil show [SECTION]	Display a section or overview	rich
sigil get <PATH>	Extract a value by dot-path	raw (scalars) / json (objects)
sigil keys [PATH]	List available keys	one per line
sigil schema	Show the structure tree	rich

Source Resolution

Use -s/--source to specify where to find brand.json:

sigil                              # cwd brand.json
sigil -s .                         # explicit cwd
sigil -s /path/to/brand.json       # absolute file path
sigil -s ../digitech               # directory containing brand.json
sigil -s digitech                  # short name → digitech/brand on Forgejo
sigil -s digitech/brand            # full owner/repo on Forgejo

Omit -s to use brand.json in the current directory. Falls back to SIGIL_SOURCE env var if set.

Dot-Path Syntax

sigil get colors.primary.hex                    # dict traversal
sigil get voice.personality.0                   # array index
sigil get accessibility.approved_pairs.0.ratio  # mixed

Output Formats

Override with --format / -f:

sigil show colors --format json     # JSON instead of rich table
sigil get name --format json        # JSON-wrapped scalar
sigil keys colors --format rich     # colored key list

Error UX

$ sigil get colors.primry.hex
Error: Key 'primry' not found in 'colors'
  Available keys: primary, secondary, text, background
  Did you mean 'primary'?

Options

Option	Description
-s, --source	Source: file, directory, remote name, or owner/repo
-f, --format	Output format: rich, json, or raw
-r, --ref	Git ref for remote sources (default: main)
--debug	Show source resolution and fetch details
--no-color	Disable color output
-v, --version	Show version

Authentication

Set FORGEJO_TOKEN for private repositories:

export FORGEJO_TOKEN="your-token-here"

Development

uv sync --extra dev
uv run pytest tests/ -v
uv run ruff check src/

Architecture

• typer — CLI framework
• httpx — HTTP client for Forgejo API
• rich — Terminal output formatting
• No Pydantic — operates on raw dicts for schema flexibility