Terraphim
v1.16.0
Terraphim
Home Releases Quickstart Docs Crates Install Donate

Quickstart

Get started with Terraphim AI in 5 minutes

27 January 2026 2 min read 256 words

Quickstart Guide

Get up and running with Terraphim AI in just 5 minutes.

Step 1: Install Terraphim

Choose your preferred installation method:

# Single command installation with platform detection
curl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash

Option B: Homebrew (macOS/Linux)

brew tap terraphim/terraphim && brew install terraphim-ai

Option C: Cargo

# Install agent with interactive TUI
cargo install terraphim-agent

# Install CLI for automation
cargo install terraphim-cli

Need more options?

Step 2: Start Server

Terraphim server provides HTTP API and knowledge graph backend.

terraphim_server

By default, server runs on http://localhost:8080.

You should see output like:

[INFO] Terraphim Server v1.16.31 starting...
[INFO] Server listening on http://localhost:8080
[INFO] Knowledge graph initialized

Step 3: Use the Agent

In a new terminal, start the interactive agent:

terraphim-agent

You'll see a welcome message and can start typing commands:

Terraphim AI Agent v1.16.31
Type 'help' for available commands

> search rust async
Found 12 results for 'rust async'

> role engineer
Role set to: Engineer (optimising for technical depth)

> search patterns
Found 8 results for 'patterns'

Common Agent Commands

Here are the most useful commands to get started:

> search <query>              # Search knowledge graph
> role <name>                 # Set search role (engineer, architect, etc.)
> connect <term1> <term2>    # Link two terms in knowledge graph
> import <file>                # Import markdown file into knowledge graph
> export <format>              # Export knowledge graph (json, csv)
> status                      # Show server status and statistics
> help                        # Show all available commands

Step 4: Import Your Content

Import your markdown files or documentation:

# Import a single file
import ~/notes/project-a.md

# Import entire directory
import ~/Documents/knowledge-base/

Step 5: Configure Data Sources

Configure Terraphim to search different sources:

# Search GitHub repositories
source add github https://github.com/terraphim/terraphim-ai

# Search StackOverflow
source add stackoverflow rust tokio

# Search local filesystem
source add filesystem ~/code/ --recursive

Step 6: Explore Features

> search how to implement async channels in rust

Role-Based Filtering

> role architect
> search system design patterns

Knowledge Graph Exploration

> connect tokio async
> show tokio

CLI Automation

For automation and scripting, use the CLI instead of REPL:

# Search and get JSON output
terraphim-cli search "async patterns" --format json

# Import files programmatically
terraphim-cli import ~/notes/*.md --recursive

# Set role and search
terraphim-cli search "rust error handling" --role engineer

Example Workflow

Here's a complete example workflow:

# 1. Start the server (in one terminal)
terraphim_server &

# 2. Import your codebase (in another terminal)
terraphim-agent
> import ~/my-project/src/

# 3. Search for information
> search error handling patterns

# 4. Set role for better results
> role senior-engineer

# 5. Search again with role context
> search error handling patterns

# 6. Export results
> export json > search-results.json

Next Steps

Getting Help

If you run into issues:

  1. Search existing GitHub issues
  2. Create a new issue
  3. Join Discord community for support
  4. Visit Discourse forum for discussions
  5. Contact us at [email protected]