Phase 6: CLI (Typer)

Phase 6: The CLI

Objective

Two CLI tools that make the association graph usable from the terminal:

assoc — query, reverse, list, path, export, create (Typer-based Python CLI)
assoc-link — create content AND associate it in one step (bash script)

What Was Built

assoc CLI (Python + Typer)

Registered as [project.scripts] in pyproject.toml. Reads YAML files directly — no server needed.

Stats

uv run assoc stats --data data/

Output

{"keys": 385, "relations": 11, "edges": 610}

Forward query — what does CISSP connect to?

uv run assoc query CISSP --data data/

Reverse query — what blocks remote work?

uv run assoc reverse remote-work --data data/

Path finding — how does A connect to B? (BFS traversal)

uv run assoc path CISSP consulting-practice --data data/

List all entities

uv run assoc list --data data/

List all relation types

uv run assoc list --relations --data data/

Create a new association

uv run assoc new RHCSA enables linux-admin-career --data data/

Export all triples as JSON (pipeable to jq)

uv run assoc export --data data/ | jq length
uv run assoc export --data data/ | jq '[.[] | select(.relation == "enables")]'

assoc-link Script (Bash)

Location: scripts/assoc-link.sh — bridges content creation and the knowledge graph.

Create an incident + associate with affected systems

assoc-link incident "DNS resolution failure" --relates-to bind-01 vyos-01 dns

Output

Creating incident: INC-2026-04-07-dns-resolution-failure
  → Use /incident skill or domus-api POST to create the document
  → Creating associations...
  ✓ INC-2026-04-07-dns-resolution-failure --links-to--> bind-01
  ✓ INC-2026-04-07-dns-resolution-failure --links-to--> vyos-01
  ✓ INC-2026-04-07-dns-resolution-failure --links-to--> dns

3 associations created.

Create a project + associate with tools and dependencies

assoc-link project "Ollama RAG" --uses python ollama --depends-on domus-api --enables natural-language-queries

Add a codex entry + auto-associate what it teaches

assoc-link codex bash traps --teaches error-handling bash-scripting

Quick note/discovery + associate what it teaches

assoc-link note "yq !!null gotcha" --teaches yq yaml-gotchas

Just create associations (no content)

assoc-link link CISSP --blocks remote-work --enables security-career

Shell Alias Setup

Add to ~/.zshrc or a dots-quantum aliases file:

alias assoc-link='bash ~/atelier/_projects/personal/association-engine/scripts/assoc-link.sh'

Available Relations

Relation Inverse Example

Relation	Inverse	Example
`uses`	`used-by`	domus-api --uses-→ fastapi
`enables`	`enabled-by`	python --enables-→ domus-api
`requires`	`required-by`	CISSP --requires-→ security-patterns
`blocks`	`blocked-by`	CISSP --blocks-→ remote-work
`depends-on`	`depended-on-by`	association-engine --depends-on-→ domus-api
`teaches`	`taught-by`	codex-bash --teaches-→ parameter-expansion
`links-to`	`linked-from`	INC-2026-04-06 --links-to-→ CR-2026-04-07
`contains`	`contained-in`	kvm-01 --contains-→ vault-01
`produces`	`produced-by`	domus-captures --produces-→ worklogs
`tracks`	`tracked-by`	edu-cissp --tracks-→ CISSP
`completes`	`completed-by`	DEPLOY-2026-03-07 --completes-→ ha-phase-3

uses

used-by

domus-api --uses-→ fastapi

enables

enabled-by

python --enables-→ domus-api

requires

required-by

CISSP --requires-→ security-patterns

blocks

blocked-by

CISSP --blocks-→ remote-work

depends-on

depended-on-by

association-engine --depends-on-→ domus-api

teaches

taught-by

codex-bash --teaches-→ parameter-expansion

links-to

linked-from

INC-2026-04-06 --links-to-→ CR-2026-04-07

contains

contained-in

kvm-01 --contains-→ vault-01

produces

produced-by

domus-captures --produces-→ worklogs

tracks

tracked-by

edu-cissp --tracks-→ CISSP

completes

completed-by

DEPLOY-2026-03-07 --completes-→ ha-phase-3

The Daily Workflow

1. Start work on something
   → assoc query <thing> --data data/
   → See what it connects to, what depends on it

2. Create content (document, incident, project)
   → /incident "description"  OR  domus-api POST
   → assoc-link incident "description" --relates-to system1 system2

3. Complete something
   → assoc-link link DEPLOY-2026-04-08 --completes ha-phase-2 --enables dns-ha

4. Review / plan
   → assoc reverse python --data data/    (what depends on Python?)
   → assoc path CISSP consulting --data data/  (how does CISSP lead to consulting?)
   → assoc list --data data/ | grep STD   (all standards in the graph)

Checklist

uv add typer completed
cli.py created with query, reverse, list, stats, path, new, export commands
[project.scripts] entry in pyproject.toml
Output is JSON — pipeable to jq
assoc-link.sh script — bridges content creation and associations
5 modes: incident, project, codex, note, link
39 tests passing
610 edges across 9 YAML files

Verification

# CLI works
uv run assoc stats --data data/

# assoc-link works
bash scripts/assoc-link.sh link test-entity --enables test-target

# Tests pass
uv run --extra dev pytest tests/ -v

# Lint clean
uv run --extra dev ruff check src/