terraphim-cli

Automation-friendly CLI for semantic knowledge graph search with JSON output.

Overview

terraphim-cli is a non-interactive command-line tool designed for scripting and automation. It provides the same semantic search capabilities as terraphim-repl but optimized for:

• JSON Output: Machine-readable output for scripts and pipelines
• Exit Codes: Proper exit codes (0 = success, 1 = error) for automation
• Shell Completions: Auto-completion for bash, zsh, and fish
• Piping: Works seamlessly in Unix pipelines

Installation

From crates.io

cargo install terraphim-cli

From Source

git clone https://github.com/terraphim/terraphim-ai
cd terraphim-ai
cargo build --release -p terraphim-cli
./target/release/terraphim-cli --help

Quick Start

Basic Search

# Search with JSON output
terraphim-cli search "rust async programming"

Output:

{
  "query": "rust async programming",
  "role": "Default",
  "results": [
    {
      "id": "doc1",
      "title": "Async Programming in Rust",
      "url": "https://rust-lang.github.io/async-book/",
      "rank": 0.95
    }
  ],
  "count": 1
}

Pretty JSON

terraphim-cli --format json-pretty search "tokio"

Pipe to jq

terraphim-cli search "rust" | jq '.results[] | .title'

Commands

search - Search Documents

terraphim-cli search <QUERY> [OPTIONS]

Options:
  --role <ROLE>      Role to use for search
  -n, --limit <N>    Maximum number of results

Examples:

# Basic search
terraphim-cli search "knowledge graph"

# With role and limit
terraphim-cli search "async" --role Engineer --limit 5

# Extract titles only
terraphim-cli search "rust" | jq -r '.results[].title'

---

config - Show Configuration

terraphim-cli config

Output:

{
  "selected_role": "Default",
  "roles": ["Default", "Engineer"]
}

---

roles - List Available Roles

terraphim-cli roles

Output:

["Default", "Engineer", "SystemOps"]

---

graph - Show Top Concepts

terraphim-cli graph [OPTIONS]

Options:
  -k, --top-k <K>    Number of concepts [default: 10]
  --role <ROLE>      Role to use

Example:

terraphim-cli graph --top-k 20 --role Engineer

Output:

{
  "role": "Engineer",
  "top_k": 20,
  "concepts": [
    "rust programming language",
    "async programming",
    "tokio runtime",
    ...
  ]
}

---

replace - Replace Terms with Links

terraphim-cli replace <TEXT> [OPTIONS]

Options:
  --format <FORMAT>  Output format: markdown, html, wiki, plain [default: markdown]
  --role <ROLE>      Role to use

Examples:

# Markdown links (default)
terraphim-cli replace "check out rust async programming"

# HTML links
terraphim-cli replace "rust and tokio" --format html

# Wiki links
terraphim-cli replace "learn rust" --format wiki

Output:

{
  "original": "check out rust async programming",
  "replaced": "check out [rust](https://rust-lang.org) [async](https://rust-lang.github.io/async-book/) programming",
  "format": "markdown"
}

---

find - Find Matched Terms

terraphim-cli find <TEXT> [OPTIONS]

Options:
  --role <ROLE>  Role to use

Example:

terraphim-cli find "rust async and tokio are great"

Output:

{
  "text": "rust async and tokio are great",
  "matches": [
    {
      "term": "rust",
      "position": [0, 4],
      "normalized": "rust programming language"
    },
    {
      "term": "async",
      "position": [5, 10],
      "normalized": "asynchronous programming"
    },
    {
      "term": "tokio",
      "position": [15, 20],
      "normalized": "tokio async runtime"
    }
  ],
  "count": 3
}

---

thesaurus - Show Knowledge Graph Terms

terraphim-cli thesaurus [OPTIONS]

Options:
  --role <ROLE>      Role to use
  --limit <LIMIT>    Maximum terms to show [default: 50]

Example:

terraphim-cli thesaurus --role Engineer --limit 10

Output:

{
  "role": "Engineer",
  "name": "engineer_thesaurus",
  "terms": [
    {
      "id": 1,
      "term": "rust",
      "normalized": "rust programming language",
      "url": "https://rust-lang.org"
    },
    ...
  ],
  "total_count": 150,
  "shown_count": 10
}

---

completions - Generate Shell Completions

terraphim-cli completions <SHELL>

Shells: bash, zsh, fish, powershell

Install Completions:

Bash:

terraphim-cli completions bash > ~/.local/share/bash-completion/completions/terraphim-cli

Zsh:

terraphim-cli completions zsh > ~/.zfunc/_terraphim-cli

Fish:

terraphim-cli completions fish > ~/.config/fish/completions/terraphim-cli.fish

---

Global Options

--format <FORMAT>   Output format: json, json-pretty, text [default: json]
--quiet             Suppress non-JSON output (errors, warnings)
--help              Print help
--version           Print version

Exit Codes

• 0 - Success
• 1 - Error (invalid input, service failure, etc.)

Scripting Examples

Search and Extract URLs

terraphim-cli search "rust documentation" | jq -r '.results[].url'

Count Results

terraphim-cli search "async" | jq '.count'

Filter by Rank

terraphim-cli search "rust" | jq '.results[] | select(.rank > 0.8)'

Loop Through Results

terraphim-cli search "tokio" | jq -r '.results[] | "\(.title): \(.url)"' | while read line; do
  echo "Found: $line"
done

Replace Text in Files

cat input.md | while read line; do
  terraphim-cli replace "$line" --format markdown | jq -r '.replaced'
done > output.md

Check if Terms Exist

if terraphim-cli find "rust tokio" | jq '.count > 0'; then
  echo "Found rust and tokio in knowledge graph"
fi

CI/CD Integration

GitHub Actions

- name: Search Knowledge Graph
  run: |
    cargo install terraphim-cli
    terraphim-cli search "deployment" --limit 10 > results.json

- name: Validate Results
  run: |
    COUNT=$(jq '.count' results.json)
    if [ "$COUNT" -eq 0 ]; then
      echo "No results found"
      exit 1
    fi

Shell Scripts

#!/bin/bash
set -e

# Search for specific terms
RESULTS=$(terraphim-cli search "api documentation" --limit 5)

# Check if we got results
if [ "$(echo $RESULTS | jq '.count')" -eq 0 ]; then
  echo "Error: No documentation found"
  exit 1
fi

# Extract URLs and fetch them
echo $RESULTS | jq -r '.results[].url' | xargs -I {} curl -s {}

Differences from terraphim-repl

Feature	terraphim-cli	terraphim-repl
Mode	Non-interactive	Interactive
Output	JSON	Pretty tables + colored
Use Case	Automation/scripts	Human interaction
Exit Codes	Proper (0/1)	N/A
Completions	Yes (bash/zsh/fish)	Command completion in REPL
Piping	Designed for it	N/A
History	No	Yes

Use terraphim-cli when:

• Writing scripts or automation
• Integrating with other tools via JSON
• CI/CD pipelines
• Batch processing
• Need machine-readable output

Use terraphim-repl when:

• Interactive exploration
• Learning the system
• Ad-hoc queries
• Human-readable output preferred

Configuration

Uses the same configuration as terraphim-repl:

• ~/.terraphim/config.json - Main configuration
• Supports role-based search
• Works offline with embedded defaults

Troubleshooting

Command Not Found

# Make sure cargo bin is in PATH
export PATH="$HOME/.cargo/bin:$PATH"

JSON Parsing Errors

# Use --quiet to suppress non-JSON output
terraphim-cli --quiet search "query" | jq '.'

Completions Not Working

# Bash: Check completion directory
ls ~/.local/share/bash-completion/completions/

# Zsh: Check fpath includes ~/.zfunc
echo $fpath

# Fish: Check completions directory
ls ~/.config/fish/completions/

Building from Source

# Debug build
cargo build -p terraphim-cli

# Release build (optimized)
cargo build --release -p terraphim-cli

# Run tests
cargo test -p terraphim-cli

# Generate docs
cargo doc -p terraphim-cli --open

Related Projects

• terraphim-repl: Interactive REPL interface
• terraphim_types: Core type definitions
• terraphim_automata: Text matching engine
• terraphim_rolegraph: Knowledge graph implementation

Support

• Discord: https://discord.gg/VPJXB6BGuY
• Discourse: https://terraphim.discourse.group
• Issues: https://github.com/terraphim/terraphim-ai/issues

License

Licensed under Apache-2.0. See LICENSE for details.

Changelog

See CHANGELOG.md for version history.