How to Use the Semantica AGI Command-Line Interface: A Complete Guide

The Semantica AGI CLI is a Click-powered interface defined in semantica/cli.py that exposes sub-commands for knowledge graph management, pipeline execution, and service orchestration through the semantica entry point.

The Semantica AGI command-line interface serves as the primary control surface for the semantica-agi/semantica repository, enabling users to configure backends, execute extraction pipelines, and query graph stores without writing Python code. Built atop the Click library with Rich formatting extensions, the CLI encapsulates the platform's core functionality into intuitive sub-commands accessible via the semantica binary.

CLI Architecture and Entry Points

The entry point resides in semantica/cli.py, where the main() function registers the top-level Click group using @click.group(). This function attaches all sub-commands and processes global flags before invoking the appropriate handler.

The implementation utilizes RichGroup, a custom subclass of click.Group that overrides format_help to render color-coded help text and structured tables using the Rich library. This provides enhanced readability for complex command hierarchies compared to standard Click output.

Context sharing between commands occurs through Click's object passing decorators. Commands annotated with @click.pass_context or @click.pass_obj receive a mutable ctx.obj dictionary containing the loaded configuration, active graph backends, and runtime state, ensuring persistent state across command invocations.

Core Commands and Usage Examples

The CLI organizes functionality into logical sub-command groups. Each group addresses specific operational domains within the Semantica ecosystem.

Knowledge Graph Operations

The kg sub-command interfaces with graph backends including Neo4j, Memory, and FalkorDB. It supports querying, importing, exporting, and visualizing graph data through Cypher or other supported query languages.

# Execute a Cypher query and receive JSON output

semantica kg query "MATCH (n:Person) RETURN n.name LIMIT 5" --json

Pipeline Execution

The pipeline sub-command manages end-to-end extraction, transformation, and loading workflows. Use run to execute pipelines, list to view available configurations, and status to monitor execution progress.

# Run the default extraction pipeline on PDF documents

semantica pipeline run --source ./data/*.pdf

Service Management

The services sub-command controls auxiliary infrastructure such as vector stores and LLM providers. It supports starting, stopping, and listing active services with simple declarative commands.

# Start a Qdrant vector store instance in the background

semantica services start --name qdrant

Interactive Configuration

The config sub-command creates and validates Semantica configuration files through interactive prompts. The init command walks users through selecting graph backends, vector stores, and LLM providers using click.prompt with click.Choice validation to ensure consistent config.yml generation.

# Initialize a new configuration file interactively

semantica config init

Interactive Shell

The shell sub-command launches an interactive REPL that mirrors the CLI context, allowing direct access to the ctx.obj dictionary and loaded backends for debugging or exploratory operations.

# Open an interactive session with current configuration loaded

semantica shell

Global Options and Error Handling

The CLI defines global options at the root level using @click.option decorators in semantica/cli.py. Available flags include --json for structured output, --quiet for suppressing non-essential logs, --no-color for disabling Rich formatting, and --dry-run for simulating execution without modifying state.

All user-visible errors raise click.ClickException, which Click formats cleanly without full Python tracebacks. This ensures the Semantica AGI CLI remains user-friendly even when operations fail or configuration errors occur.

Plugin Architecture and Extensions

The CLI dynamically loads extensions from the plugins/ directory, enabling community-driven functionality without modifying core source code. This plugin system scans the directory at startup and registers additional sub-commands based on discovered modules, automatically integrating them into the help system.

Summary

• The Semantica AGI CLI entry point is defined in semantica/cli.py with the main() function registering all sub-commands via Click decorators
• RichGroup provides enhanced color-coded help formatting beyond standard Click output
• Commands utilize @click.pass_obj to share configuration and backend instances through the ctx.obj context dictionary
• Core sub-commands include kg for graph operations, pipeline for ETL workflows, services for infrastructure management, and config for interactive setup
• Global flags like --json, --quiet, and --dry-run control output format and execution behavior across all commands
• The plugin system automatically loads extensions from the plugins/ directory at startup, extending CLI capabilities dynamically

Frequently Asked Questions

How do I install the Semantica AGI command-line interface?

The CLI installs automatically when you install the Semantica AGI package from the semantica-agi/semantica repository. After installation, the semantica binary becomes available in your PATH, providing immediate access to all sub-commands defined in semantica/cli.py.

Where is the CLI entry point defined in the source code?

The entry point is implemented in semantica/cli.py within the main() function. This function uses @click.group() to create the root command group and registers all sub-commands including kg, pipeline, services, config, and shell.

How does the CLI handle configuration between commands?

The CLI uses Click's context passing mechanism through ctx.obj, a mutable dictionary shared across commands via @click.pass_obj decorators. This object stores the loaded YAML configuration, active graph backend connections, and vector store instances, ensuring state persistence throughout the command lifecycle.

Can I extend the CLI with custom commands?

Yes, the CLI supports dynamic extension loading from the plugins/ directory. Place Python modules containing Click commands in this directory, and the CLI will automatically discover and register them at startup, integrating them into the help system and command hierarchy.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}