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

> Master the Semantica AGI command-line interface with our complete guide. Learn to manage knowledge graphs, run pipelines, and orchestrate services using the semantica CLI.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-13

---

**The Semantica AGI CLI is a Click-powered interface defined in [`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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.

```bash

# 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.

```bash

# 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.

```bash

# 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`](https://github.com/semantica-agi/semantica/blob/main/config.yml) generation.

```bash

# 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.

```bash

# 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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/cli.py).

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

The entry point is implemented in [`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/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.