cli-tree

Visualize and explore any CLI. Parse help output, mine your shell history for real usage patterns, and (via a coding-agent skill) run LLM archaeology to discover hidden flags and canonical workflows.

Zero dependencies. Bun-native. Works as a library, a binary, or a skill for Claude Code / Cursor / Codex.

What it does

           ┌─────────────┐
           │   cli-tree  │
           └──────┬──────┘
                  │
      ┌───────────┼───────────┐
      ▼           ▼           ▼
  ┌──────┐   ┌────────┐   ┌───────────┐
  │ tree │   │  mine  │   │archaeology│
  └──────┘   └────────┘   └───────────┘
     │           │              │
  --help     shell history     LLM
  parser     markov chain   (via skill)

Four things:

1. tree — parse --help output of any CLI into a navigable box-drawing tree. 53+ real CLIs tested.
2. flow — render workflow YAML files as terminal DAGs (6 curated examples).
3. mine — analyze your shell history, detect repeated sequences, surface skill suggestions.
4. archaeology — merge all three + LLM-proposed hidden flags, validated against real --help.

Install

From npm (recommended):

# One-shot (no install)
bunx @crafter/cli-tree git
npx  @crafter/cli-tree git

# Global install
bun add -g @crafter/cli-tree
npm i  -g @crafter/cli-tree

# Then
clitree git
clitree mine bun
clitree archaeology docker

As a library in your project:

bun add @crafter/cli-tree

import { parseHelpRecursive } from "@crafter/cli-tree";
import { mineCli } from "@crafter/cli-tree/miner";
import { runArchaeology } from "@crafter/cli-tree/archaeology";

From source:

git clone https://github.com/crafter-station/cli-tree
cd cli-tree
bun install
bun src/cli.ts --help

Usage

Tree — parse any CLI's help output

clitree git
clitree docker --depth 2
clitree kubectl --compact --no-flags
clitree bun --format html > bun-tree.html
docker --help | clitree --stdin docker

Flow — render workflow YAML as DAG

clitree flow workflows/git-pr-flow.yml
clitree flow workflows/docker-deploy.yml --format html

Workflow YAML looks like:

name: pr-flow
cli: git
description: Typical flow for creating a pull request
nodes:
  - id: add
    command: git add .
  - id: commit
    command: git commit
  - id: push
    command: git push
  - id: pr
    command: gh pr create
    optional: true
edges:
  - add -> commit
  - commit -> push
  - push -> pr

Output (ASCII, ANSI, or HTML):

git · pr-flow
Typical flow for creating a pull request

┌─────────────────┐
│     git add     │
└─────────────────┘
         │
         ▼
┌─────────────────┐
│   git commit    │
└─────────────────┘
         │
         ▼
┌─────────────────┐
│    git push     │
└─────────────────┘
         │
         ▼
┌┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┐
┊  gh pr create   ┊
└┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┘

Mine — discover workflows from your shell history

clitree mine git
clitree mine docker --min-support 5
clitree mine bun --format json > bun-flows.json

Example output against real zsh history:

git — shell history analysis

Usage:
  Invocations:  1257
  Subcommands:  31
  Sessions:     483

Top subcommands:
  commit               ██████████████████████████████ 277
  checkout             ██████████████████████████     237
  push                 ████████████████████           183
  add                  ██████████████████             167
  pull                 █████████████                  124

Discovered workflows:
  add → commit               (116×)
  commit → push              (85×)
  add → commit → push        (64×)
  checkout → pull            (38×)

💡 Skill suggestions:

  [MED] /ship — Run git add, then commit, then push as one command
    You run this exact sequence 64 times — that's a lot of repetition
    git add && git commit && git push

Archaeology — full analysis

clitree archaeology git             # deterministic phases
clitree archaeology docker --no-cache

Without the skill, archaeology runs --help parsing + history mining. For LLM-backed hidden-flag discovery, install the clitree skill (see below).

The clitree skill

The LLM-archaeology phase lives in a coding-agent skill. It is agent-agnostic: the skill is just markdown instructions that any coding agent (Claude Code, Cursor, Codex, Aider) can execute.

Install:

bash ./skill/install.sh

Then, inside your coding agent:

/clitree git

The agent will:

1. Parse git --help recursively.
2. Mine your shell history for real workflows.
3. Use its own LLM to propose hidden/undocumented flags.
4. Validate every proposal by running git <sub> --help and checking man pages.
5. Reject hallucinations automatically — only flags that actually exist make it into the final tree.
6. Suggest new skills based on workflows you repeat often.

No API keys. No external services. Works entirely inside your coding agent.

How archaeology works

The key insight is that an LLM's knowledge of a CLI is unreliable alone but rich when validated. Archaeology uses a closed loop:

┌─────────────┐     proposes       ┌───────────────┐
│   The LLM   │ ─────────────────► │  cli-tree     │
│  (in agent) │                    │  validator    │
└─────────────┘                    └───────┬───────┘
      ▲                                    │
      │ next proposal                      │ runs
      │                                    ▼
      │                          ┌──────────────────┐
      │                          │ <cli> <sub>      │
      └──────  verdict ─────────│ --help / man     │
                                  └──────────────────┘
                                  verify or reject

• LLM proposes → hidden flags, canonical workflows, constraint maps
• Code executes → git commit --fixup → real output → compare
• Truth survives → only verified facts become part of the enriched tree

Every piece of data carries a source tag:

| Source | Confidence | Behavior | |--------|-----------|----------| | help | 1.0 | From parsed --help output | | llm-validated | 0.9 | LLM proposed, confirmed by --help | | man | 0.85 | From man page | | llm-deep-dive | 0.6 | LLM proposed, not confirmed (shown with --include-unverified) | | llm-survey | 0.2 | LLM hypothesis, rejected by validation |

By default, only sources above llm-validated are shown.

Architecture

src/
├── parse.ts            # --help parser (53 CLIs tested)
├── tree.ts             # tree renderer (box-drawing)
├── compile.ts          # chart primitives
│
├── miner/              # shell history mining
│   ├── history.ts      # zsh/bash/fish parser
│   ├── sessions.ts     # temporal segmentation
│   ├── transitions.ts  # markov chain
│   ├── workflows.ts    # path clustering
│   ├── stats.ts        # usage statistics
│   └── suggest.ts      # skill suggestions
│
├── archaeology/        # LLM-backed exploration
│   ├── types.ts        # Source/EnrichedCLINode
│   ├── prompts.ts      # 4-phase prompt templates
│   ├── validate.ts     # closed-loop validation
│   ├── merge.ts        # multi-source merge
│   ├── cache.ts        # ~/.clitree/cache/
│   ├── delegate.ts     # agent-agnostic delegate
│   └── orchestrator.ts # runs all phases
│
├── flow/               # workflow DAG rendering
│   ├── types.ts
│   ├── yaml.ts         # zero-dep YAML parser
│   ├── layout.ts       # rank-based layout
│   ├── render.ts       # box-drawing DAG
│   └── encode.ts
│
└── cli.ts              # binary entrypoint

Tests

bun test                          # run all (~290 tests)
bun test tests/flow               # flow subsystem
bun test tests/miner              # miner subsystem
bun test tests/archaeology        # archaeology subsystem
bun test tests/parse-real-clis    # 53+ real CLIs

Recent run: 287 tests passing, 0 fails across 8 test files.

Roadmap

• [x] --help parser (53 CLIs)
• [x] Box-drawing tree renderer (ANSI / string / HTML)
• [x] Workflow YAML DAG renderer
• [x] Shell history miner (zsh / bash / fish)
• [x] Skill suggestions from repeated workflows
• [x] Archaeology types + validation loop + merge
• [x] Disk cache
• [x] Agent-agnostic skill
• [ ] Makefile / package.json / Dockerfile scraping
• [ ] Interactive TUI mode
• [ ] Mermaid export for flows

License

MIT