ExoGraph API

Appearance

Command-Line Interface (CLI) ​

ExoGraph provides a powerful command-line interface for uploading documents and querying knowledge graphs directly from your terminal.

Installation ​

bash
# Install from source
cd cli
pip install -e .

# Or with conda
conda activate exograph
cd cli
pip install -e .

Quick Start ​

1. Configure API Key ​

Get your API key from exograph.ai → Settings → API Keys

bash
exograph config set api-key exo_key_live_...

2. Upload Documents ​

bash
# Upload to private graph
exograph upload document.pdf --scope private

# Upload to world graph (shared)
exograph upload paper.pdf --scope world

3. Query Knowledge Graphs ​

bash
# Query world graph
exograph query "what is machine learning?" --scope world

# Query private graph
exograph query "tell me about X" --scope private

# Use specific model
exograph query "analyze this" --model ponder

# Save response to file
exograph query "explain transformers" --output response.md

Commands ​

exograph upload ​

Upload documents to ExoGraph.

Usage:

bash
exograph upload <file> [options]

Options:

  • --scope, -s: Graph scope (world or private, default: from config)
  • --progress, -p: Show upload progress
  • --endpoint, -e: Override API endpoint

Examples:

bash
# Single file upload
exograph upload document.pdf

# Upload with scope
exograph upload paper.pdf --scope private

# Upload with progress tracking
exograph upload large-doc.pdf --progress

Supported Formats:

  • PDF (.pdf)
  • Microsoft Word (.docx)

exograph query ​

Query ExoGraph knowledge graphs.

Usage:

bash
exograph query <question> [options]

Options:

  • --scope, -s: Graph scope (world or private, default: from config)
  • --model, -m: Model (snap or ponder, default: from config)
  • --graph-id, -g: Query specific graph by ID
  • --output, -o: Save response to file
  • --endpoint, -e: Override API endpoint

Examples:

bash
# Simple query
exograph query "what is machine learning?"

# Query with model selection
exograph query "analyze this deeply" --model ponder

# Query specific graph
exograph query "what's in this document?" --graph-id graph_abc123

# Save response
exograph query "explain transformers" --output response.md

exograph list ​

List documents, graphs, or sessions.

Usage:

bash
exograph list <resource> [options]

Resources:

  • documents - List all documents
  • graphs - List all graphs

Options:

  • --scope, -s: Filter by scope (world or private)
  • --verbose, -v: Show detailed information
  • --endpoint, -e: Override API endpoint

Examples:

bash
# List all documents
exograph list documents

# List private documents
exograph list documents --scope private

# List graphs with details
exograph list graphs --verbose

exograph research ​

Manage research sessions.

Usage:

bash
exograph research <command> [options]

Commands:

  • start <topic> - Start a new research session
  • list - List research sessions
  • status <session-id> - Check research session status
  • delete <session-id> - Delete a research session

Options:

  • --scope, -s: Research scope (world or private, default: world)
  • --mode: Research mode (auto, manual, systematic, curious, deep_dive, default: auto)
  • --model: Model (snap or ponder, default: ponder)
  • --max-iterations: Maximum iterations (default: 1)
  • --budget: Budget limit in credits
  • --graph-id: Target graph ID

Examples:

bash
# Start research
exograph research start "quantum computing" --scope world

# List research sessions
exograph research list --scope world

# Check status
exograph research status 550e8400-e29b-41d4-a716-446655440000

# Delete research session
exograph research delete 550e8400-e29b-41d4-a716-446655440000

exograph document ​

Manage documents.

Usage:

bash
exograph document <command> [options]

Commands:

  • get <doc-id> - Get document details
  • delete <doc-id> - Delete a document
  • chunks <doc-id> - List chunks for a document

Options:

  • --scope, -s: Graph scope (world or private, default: world)
  • --endpoint, -e: Override API endpoint

Examples:

bash
# Get document details
exograph document get 00f1e557-7080-472c-9527-1ee6a9d35652 --scope world

# List document chunks
exograph document chunks 00f1e557-7080-472c-9527-1ee6a9d35652

# Delete document
exograph document delete 00f1e557-7080-472c-9527-1ee6a9d35652

Search documents and entities.

Usage:

bash
exograph search <resource> <query> [options]

Resources:

  • documents - Search documents by semantic similarity
  • entities - Search for entities in knowledge graphs

Options:

  • --scope, -s: Search scope (world or private, default: world)
  • --limit: Maximum number of results (default: 10)
  • --endpoint, -e: Override API endpoint

Examples:

bash
# Search documents
exograph search documents "machine learning" --scope world

# Search entities
exograph search entities "deep learning" --limit 5

exograph graph ​

Manage knowledge graphs.

Usage:

bash
exograph graph <command> [options]

Commands:

  • create <name> - Create a new graph
  • get <graph-id> - Get graph metadata
  • show <graph-id> - Show graph data (nodes and edges)
  • delete <graph-id> - Delete a graph

Options:

  • --scope, -s: Graph scope (world or private, default: world)
  • --endpoint, -e: Override API endpoint

Examples:

bash
# Create graph
exograph graph create "My Research Graph" --scope private

# Show graph data
exograph graph show world --scope world

# Delete graph
exograph graph delete graph_abc123 --scope private

exograph chat ​

Manage chat sessions and conversations.

Usage:

bash
exograph chat <command> [options]

Commands:

  • send <message> - Send a chat message (creates session if needed)
  • create <title> - Create a new chat session
  • sessions - List chat sessions
  • show <session-id> - Show a chat session with all messages
  • delete <session-id> - Delete a chat session

Options:

  • --scope, -s: Chat scope (world or private, default: world)
  • --model: Model (snap or ponder, default: snap)
  • --reasoning: Reasoning engine (rag, graph, web, default: graph)
  • --session-id: Existing session ID for send command
  • --graph-id: Target specific graph ID
  • --endpoint, -e: Override API endpoint

Models:

  • snap: Fast responses for quick conversations
  • ponder: Deep thinking for complex analysis

Examples:

bash
# Send message (creates session automatically)
exograph chat send "Tell me about IBM" --scope world

# Create chat session
exograph chat create "ML Discussion" --model ponder --scope world

# List chat sessions
exograph chat sessions --scope world

# Show chat session
exograph chat show 61124873-a318-47be-9ffe-3d6e220df3d1

# Delete chat session
exograph chat delete 61124873-a318-47be-9ffe-3d6e220df3d1

exograph config ​

Manage CLI configuration.

Usage:

bash
exograph config <command> [options]

Commands:

  • show - Display current configuration
  • set <key> <value> - Set configuration value
  • reset - Reset to defaults

Configuration Keys:

  • api-key - Your ExoGraph API key
  • endpoint - API endpoint URL (default: https://exograph.ai)
  • scope - Default graph scope (world or private)
  • model - Default model (snap or ponder)

Examples:

bash
# Show current config
exograph config show

# Set API key
exograph config set api-key exo_key_live_...

# Set default scope
exograph config set scope private

# Set default model
exograph config set model ponder

# Reset configuration
exograph config reset

Configuration ​

Configuration is stored in ~/.exograph/config.yaml:

yaml
api_key: exo_key_live_...
endpoint: https://exograph.ai
default_scope: world
default_model: snap

You can also use environment variables:

  • EXOGRAPH_API_KEY - API key (takes precedence over config file)
  • EXOGRAPH_ENDPOINT - API endpoint (takes precedence over config file)

Graph Scopes ​

World Graph (world) ​

  • Shared knowledge accessible to all users
  • Contribute documents to earn tokens when others query your knowledge
  • Default scope for new installations

Private Graph (private) ​

  • Personal knowledge base isolated to your account
  • Documents stay private and are only accessible to you
  • Perfect for sensitive documents or personal research

Authentication ​

The CLI uses the same authentication system as the REST API:

  1. API Key Authentication: Set via exograph config set api-key or EXOGRAPH_API_KEY environment variable
  2. Automatic User ID: The backend extracts your user ID from the API key automatically
  3. Secure Storage: API keys are stored locally in ~/.exograph/config.yaml

Get your API key from:

  • Web UI: exograph.ai/app → Settings → API Keys
  • Dashboard: Navigate to your profile settings

Examples ​

Complete Workflow ​

bash
# 1. Configure CLI
exograph config set api-key exo_key_live_abc123...
exograph config set scope private

# 2. Upload documents
exograph upload research-paper.pdf --scope private
# ✓ Uploaded research-paper.pdf (doc_xyz789)
# ✓ Created graph graph_abc123

# 3. Query knowledge
exograph query "what is the main contribution of the paper?"
# [Response with sources and citations]

# 4. List documents
exograph list documents --scope private
# Shows all your private documents

# 5. Query world graph
exograph query "what is machine learning?" --scope world
# Queries shared knowledge

Batch Operations ​

bash
# Upload multiple files (one at a time)
for file in *.pdf; do
  exograph upload "$file" --scope private
done

# Query and save results
exograph query "explain transformers" --output transformers.md
exograph query "what is GPT?" --output gpt.md

Troubleshooting ​

API Key Not Configured ​

bash
Error: API key not configured. Run 'exograph config set api-key <your-key>'

Solution: Set your API key using exograph config set api-key <your-key>

Invalid or Expired API Key ​

bash
Error: Invalid or expired API key. Check your configuration.

Solution:

  1. Verify your API key is correct
  2. Check if the key has expired in the web UI
  3. Generate a new API key if needed

Network Errors ​

bash
Error: Network error: Connection refused

Solution:

  • Check your internet connection
  • Verify the endpoint: exograph config show
  • Try overriding endpoint: exograph query "test" --endpoint http://localhost

File Upload Errors ​

bash
Error: Unsupported file type: .txt. Only PDF and DOCX are supported.

Solution: Convert your file to PDF or DOCX format before uploading

Advanced Usage ​

Local Development ​

For local development, override the endpoint:

bash
exograph upload test.pdf --endpoint http://localhost
exograph query "test" --endpoint http://localhost

Scripting ​

The CLI is designed to be script-friendly:

bash
#!/bin/bash
# Upload script
for file in documents/*.pdf; do
  exograph upload "$file" --scope private
done

# Query script
response=$(exograph query "what is X?" --scope world)
echo "$response" > response.txt

See Also ​

Released under the MIT License.

Copyright © 2025 ExoGraph