semantica/docs/cli-setup.md

title, description, icon

title	description	icon
CLI Setup	The five Semantica executables — what each one does, when to use it, and how to confirm it is working.	terminal

Installing the base package registers five executables on your PATH. Each serves a distinct purpose. This page explains what they are, how to verify they are available, and which one to reach for in each situation.

Installed Commands

pip install semantica

After installation the following commands are available:

Command	Entry point	What it does
semantica	semantica.cli:main	General-purpose CLI for pipeline runs, extraction, and graph operations
semantica-server	semantica.server:main	FastAPI/uvicorn REST API server bound to 0.0.0.0:8000
semantica-worker	semantica.worker:main	Background worker process entry point for Semantica deployments
semantica-explorer	semantica.explorer:main	Interactive browser dashboard for knowledge graph exploration
semantica-mcp	semantica.mcp_server:main	MCP server (stdio) for Claude Desktop, Cursor, Windsurf, and other MCP clients

`semantica-explorer` requires `pip install semantica[explorer]`. Running it without that extra will immediately print an error and exit. See [Explorer Setup](explorer-setup) for the full walkthrough.

Verify the Installation

Confirm each command is reachable and prints its usage:

semantica --help
semantica-server --help
semantica-worker --help
semantica-explorer --help
semantica-mcp --help

Confirm the package version:

python -c "import semantica; print(semantica.__version__)"

When to Use Each Command

The general-purpose CLI. Use it for one-off pipeline runs, entity extraction, and graph operations from a shell script or CI job. Starts the REST API server. Binds to `0.0.0.0:8000`. Use this when another service or application needs programmatic access to Semantica over HTTP. Background task processor. Run alongside `semantica-server` when you need async pipeline execution outside the request cycle. Start the server first, then start one or more workers pointing at the same backend. Launches the browser dashboard. Requires `pip install semantica[explorer]`. Use this to explore a saved knowledge graph interactively. See [Explorer Setup](explorer-setup). Runs the MCP server over stdio. Configure it in your MCP client's settings file to expose all 12 tools and 3 resources to Claude Desktop, Cursor, Windsurf, or any MCP-aware client. See [MCP Server](reference/mcp_server).

Usage Examples

```bash # Starts FastAPI + uvicorn on 0.0.0.0:8000 semantica-server ```

Once running, check it with:

```bash
curl http://localhost:8000/health
# {"status": "healthy"}

curl http://localhost:8000/api/info
# {"name": "Semantica API", "version": "...", "status": "active"}
```

The interactive API docs are at `http://localhost:8000/docs`.

```bash semantica-worker ```

The worker exits cleanly on `SIGINT` (Ctrl-C) or `SIGTERM`.

Add to your MCP client's settings file:

```json
{
  "mcpServers": {
    "semantica": {
      "command": "semantica-mcp"
    }
  }
}
```

Or use the Python module form if the command is not on `PATH`:

```json
{
  "mcpServers": {
    "semantica": {
      "command": "python",
      "args": ["-m", "semantica.mcp_server"]
    }
  }
}
```

Test it directly before configuring your client:

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | semantica-mcp
```

You should receive a JSON-RPC response. See [MCP Server](reference/mcp_server) for the full list of tools and resources.

```bash pip install semantica[explorer] semantica-explorer --graph my_graph.json ```

See [Explorer Setup](explorer-setup) for the full walkthrough including how to build and save a graph file.

Every command also runs as a Python module — useful when the script directory is not on `PATH`:

```bash
python -m semantica.mcp_server
python -m semantica.explorer --graph my_graph.json
```

Environment Variables

semantica-mcp reads two environment variables:

Variable	Default	Description
SEMANTICA_KG_PATH	(none)	Path to a saved graph file to load on startup
SEMANTICA_LOG_LEVEL	WARNING	Log verbosity: DEBUG, INFO, WARNING

semantica-server reads one:

Variable	Default	Description
SEMANTICA_CORS_ORIGINS	http://localhost:5173,http://127.0.0.1:5173	Comma-separated list of allowed CORS origins

No other environment variables are read by these commands.

Troubleshooting

command not found

The executables are placed in the bin/ (Linux/Mac) or Scripts/ (Windows) directory of the active Python environment. If the command is not found, that directory is likely not on PATH.

Activate your virtual environment first:

source venv/bin/activate   # Linux / Mac
venv\Scripts\activate      # Windows
semantica --help

Find where pip placed the scripts:

python -m site --user-scripts   # user-level install
pip show -f semantica           # shows installed files

Command found but crashes on import

pip install --upgrade semantica
python -c "import semantica; print(semantica.__version__)"

If you have multiple Python environments, make sure you are installing into the same one the shell resolves:

python -m pip install semantica

semantica-explorer — "uvicorn is required"

The Explorer extras are not included in the base install:

pip install semantica[explorer]

semantica-mcp silent failure in a MCP client

The MCP server communicates over stdio. Test it directly from the shell first:

echo '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}' | semantica-mcp

A response of {"jsonrpc":"2.0","id":1,"result":{}} confirms the server is working. If you see nothing, check that the command is on PATH and the base package is installed.

Windows: DLL errors on startup

Install the Microsoft Visual C++ Redistributable. This is a Windows system dependency required by PyTorch and related packages, not a Semantica bug.

Next Steps

Build a graph, save it, and launch the browser dashboard. All 12 tools and 3 resources exposed over the MCP protocol. Virtual environments, optional extras, and platform-specific notes. End-to-end pipeline walkthrough with working code.