cli.md

Concepts

• Document: a tree of nodes

  • can be of type text (for base model completions) or chat
  • serialized to a JSON file in [loom_dir]/json

• Node: a single unit of text content, with metadata

  • can have one parent and any number of children
  • can be written by the user with add, or generated by a model and stored in the document as a child node

• ID: generated UUIDs for nodes and documents

• Node reference: a string that references a node. Accepts:

  • full or partial (e.g., a8e3) ID
  • positional selector (^ for parent, </> for siblings) relative to the currently selected node
    • supports multiple characters or numbers to traverse multiple nodes, e.g. ^2 or ^^ for the parent of the parent node
      • ^-1 targets the current lineage's root node
  • [doc_id]:[node_id] to reference a node in a specific document without affecting the current selection

Inference refers to the process of making a request to a model inference API to produce a set of n completions for a given input (context).

Context refers to the text that is submitted to a model for inference. Chat models receive context as a list of messages, while text models receive it as a single string. Document nodes are compiled into context at inference time.

Commands

Documents

new

Create a new document.

• Include a string (e.g., loom new "hello") to initialize with content.
• Use --chat to create a chat document (default is text).
• Optionally, use:
  • --from-file|-f to load content from a file path
  • --editor|-e to invoke an instance of your $EDITOR for multiline input

Examples:

Action	Command
Create a new text document	loom new
Create a new chat document	loom new --chat
Create a new document with initial content	loom new "Loom is a multiversal"
Create a new document and write content in $EDITOR	loom new --editor
Create a new document, loading content from a file	loom new --from-file input.txt

ls

List:

• documents present in the datastore with --docs|-d, or
• node sets ("loom points") defined in a target YAML file for loading into the current document with load
  • a given index can be specified with --index|-i: loom ls data/nodes/samples.yaml --index 0 will display the file's first item
  • if no index is specified, all items will be listed

Examples:

Action	Command
List all documents	loom ls --docs
List all nodes in a YAML file	loom ls data/nodes/samples.yaml
List properties of a specific item in a YAML file	loom ls data/nodes/samples.yaml --index 0

load

Load node(s) into the current document from a YAML file, Loomsidian JSON, or arbitrary Markdown file.

• Compatible YAML files must be in the format shown in data/nodes/samples.yaml
  • the input argument can be a file path or a GitHub Gist URL/ID (see below for examples)
  • an index must be specified with --index|-i: loom load data/nodes/samples.yaml --index 0 will load and select the file's first item
  • --select|-S can be set to root, last (default), or none to [not] select a specific node after loading
• Loomsidian provides an export button at the top of its Loom panel. load will import all nodes from a given export into the current/target document
  • bookmarked nodes' scores will be set to 1
• Markdown files are supported when specified as a file path or URL
  • --split-symbol|-s can be used to specify a heading level to split on (e.g., h2), resulting in a branch made up of one node per heading (default: h2)

-t|--target can be used to specify a target document to load node(s) into.

Examples:

Action	Command
Load nodes from a YAML file	loom load data/nodes/samples.yaml --index 0
Load nodes from a GitHub Gist	loom load gist:jmpaz/6c58b2027df085f7d72ad2bea513c59d
Load nodes from a Markdown file, splitting on H4 headings	loom load notes.md --split-symbol h4
Load nodes into a specific document	loom load data.yaml --target dd6ad

Nodes

add

Add a node to the current document.

Option	Description
--parent, -p	Reference to parent node for the new node (optional)
--split, -s	Split the target node at the cursor position (if set) before adding the new child node
--as-root, -r	Add as a new root node (default is to add as child of the current node)
--no-select, -n	Don't select the new node after adding
--role	Set the message role (chat only, either user or assistant)
--from-file, -f	Read content from the specified file path
--editor, -e	Spawn an $EDITOR instance for multiline input (save and exit to add the node)

Examples:

Action	Command
Add a node with content	loom add "This is a new node"
Add a node with content loaded from a file	loom add --from-file content.txt
Add a node as a root node	loom add --as-root "This is a root node"
Add a node with a specific parent	loom add --parent 7a424 ", and this is a child"
Add a node, writing content in $EDITOR	loom add --editor

select

Select a node, document, or the parent of the current node. Position the cursor within the selected node.

• Usage: loom select [node_reference] or loom select --doc [document_id]
• Options:
  • --doc, -d: Select a document instead of a node
  • --parent, -p: Select the parent of the current node
  • --cursor, -c: Set the cursor position within the selected node
    • Supports positioning by character index (12), word (w2), column + index/word (2,w2), or string ("cool")
  • --cursor-pre, -C: same as --cursor, but set the cursor position preceding the specified position

Examples:

Action	Command
Select a node by ID	loom select 88427
Select the parent of the current node	loom select --parent
Set cursor position within the selected node	loom select -c 10
Select node aad74 and set cursor position to the word "cool"	loom select aad74 -c "cool"
Select a node (a8a54) in a not-yet-selected document (b43ba)	`loom select b43ba:a8a54
Select a document	loom select --doc ea569

edit

Edit the content of a node.

• Usage: loom edit [content]
• Options:
  • --node-id, -i: Specify the node to edit (default is the currently selected node)
  • --new, -n: Create a new node with the updated content instead of modifying the existing node
  • --no-select: When editing an unselected node, don't select the updated node
  • --from-file, -f: Read content from the specified file path

If no content is provided, the $EDITOR will be invoked to edit the node's content.

Examples:

Action	Command
Edit the current node	loom edit
Edit the selected node, loading content from a file	loom edit --from-file content.txt
Edit node aad74	loom edit --node-id aad74
Edit a duplicate of the target node instead of editing in place	loom edit --new

show

Display the content, context, or metadata of a node.

Shell affordances

If you're using this package for its command-line interface, you will get the most out of it if you're empowered (rather than inhibited) by your terminal environment.

The following command-line tools pair well with loom:

Functionality	Utilities
Terminal multiplexer	tmux, zellij
User-friendly shell	fish, nushell, zsh(+)
Line/token counting	wc, ttok
Recall commands from shell history	atuin
Navigate to relevant directories	zoxide
Minimal shell prompt	starship