Skip to content

cli-tree.md

Latest commit

 

History

History
157 lines (117 loc) · 5.21 KB

cli-tree.md

File metadata and controls

157 lines (117 loc) · 5.21 KB

IWE Tree

Display document hierarchy as a tree structure.

Usage

iwe tree [OPTIONS]

Options

Option Default Description
-f, --format <FORMAT> markdown Output format: markdown, keys, json, yaml.
-d, --depth <DEPTH> 4 Maximum depth to traverse.
--filter <EXPR> - Inline YAML filter expression. See Query Language.
-k, --key <KEY> - Start tree from specific document(s); repeatable.
--includes <KEY[:DEPTH]> - $includes anchor. Repeatable; anchors are ANDed.
--included-by <KEY[:DEPTH]> - $includedBy anchor. Repeatable; anchors are ANDed.
--references <KEY[:DIST]> - $references anchor. Repeatable; anchors are ANDed.
--referenced-by <KEY[:DIST]> - $referencedBy anchor. Repeatable; anchors are ANDed.
--max-depth <N> 1 Session default for inclusion anchor flags without a colon-suffix. 0 = unbounded.
--max-distance <N> 1 Session default for reference anchor flags without a colon-suffix. 0 = unbounded.
-v, --verbose <LEVEL> 0 Verbosity level (1=info, 2=debug).

When filter or anchor flags are provided, the selector resolves to a set of keys and those keys are used as the tree roots. Combining -k with the selector intersects the two — empty intersection yields an empty tree.

Output Formats

Markdown (default)

Nested list with links:

- [Main Document](main)
  - [Child Document](child)
    - [Nested Item](nested)
- [Another Root](another)

Keys

Document keys only with tab indentation:

main
	child
		nested
another

JSON

Nested JSON array structure:

[
  {
    "key": "main",
    "title": "Main Document",
    "children": [
      {
        "key": "child",
        "title": "Child Document",
        "children": []
      }
    ]
  }
]

children is always present (empty array on leaves). With --project f1,f2, the listed user-frontmatter fields are emitted alongside key, title, children per node:

iwe tree --project pillar,status -f json

Starting from Specific Documents

Use -k to start the tree from specific document(s):

iwe tree -k my-doc
iwe tree -k doc-a -k doc-b

This is essential for documents involved in circular references that have no natural root.

Handling Circular References

When documents form circular references (A→B→C→A), they have no natural root and won't appear in the default tree output. Use -k to start from any document in the cycle:

iwe tree -k doc-a

Output shows the cycle:

- [Doc A](doc-a)
  - [Doc B](doc-b)
    - [Doc C](doc-c)
      - [Doc A](doc-a)

Examples

iwe tree
iwe tree -f keys
iwe tree -f json
iwe tree -f yaml
iwe tree -k my-doc
iwe tree -k doc-a -k doc-b
iwe tree --depth 2
iwe tree | grep -i api
iwe tree -f keys | grep cli

# Roots inside an anchor's subtree
iwe tree --included-by projects/alpha:0

# Tree restricted to drafts
iwe tree --filter 'status: draft'

Depth Impact

Depth Shows
1 Root documents only
2 Roots and their direct children
3 Up to grandchildren
4+ Deeper nested relationships

AI Agent Tips

  • Use tree to understand the overall structure of a knowledge base
  • Use -f keys for programmatic processing
  • Use -f json or -f yaml for structured data consumption
  • Pipe through grep to filter results
  • Use -k to explore documents involved in circular references
  • Use --depth 2 to quickly identify major topic areas

Deprecated aliases

The following flags pre-date the query language and remain accepted for backward compatibility. Each invocation prints a one-line warning: ... is deprecated to stderr.

Deprecated Use instead
--in KEY[:N] --included-by KEY[:N]
--in-any K1 K2 --filter '$or: [{ $includedBy: K1 }, { $includedBy: K2 }]'
--not-in KEY --filter '$nor: [{ $includedBy: KEY }]'
--refs-to KEY --references KEY (legacy semantics: ORs $includes and $references)
--refs-from KEY --referenced-by KEY (legacy semantics: ORs $includedBy and $referencedBy)