Log in Explore Cloud
version:0.2 doc:getting-started updated:2026

Getting Started

This guide shows both normal starting points: a uv-managed install inside your own project folder, and a source checkout for contributors who want to run the repository examples.

1. Install with uv or from source
uv project 
mkdir semantic-rails-demo
cd semantic-rails-demo
uv venv .venv
source .venv/bin/activate
uv pip install 'semantic-rails>=0.2.0'
other environment managers 
mkdir semantic-rails-demo
cd semantic-rails-demo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'semantic-rails>=0.2.0'
source checkout 
git clone https://github.com/semantic-rails/semantic-rails.git
cd semantic-rails
uv venv
uv sync --group dev

Use uv for the default local setup. Other Python environment managers are fine as long as Semantic Rails is installed into the environment that will launch the CLI and MCP processes. Use the source checkout when you are contributing or want the checked-in examples under examples/.

2. Create your first package
terminal 
semantic-rails setup --interactive
semantic-rails project status --path ./my_package
semantic-rails repl --path ./my_package
semantic-rails ask --path ./my_package "total amount by event type" --run
semantic-rails mcp setup --path ./my_package

The wizard can create the package, set the local profile, validate it, and optionally add the Query MCP and Architect MCP to Claude Desktop or Codex. On POSIX it can also start a managed MCP HTTP server; on Windows it uses client-launched stdio or a foreground HTTP terminal. For automation, use semantic-rails init my_package --yes with explicit --path arguments.

This is the deterministic setup layer for a new project. It creates a split-layout package with starter data, examples, and package-local tests. Architect MCP can guide the same workflow from an MCP client, but the terminal path is always available.

Package commands for a pip-created project usually use --path ./my_package.

The REPL is optional. It is useful for local authoring loops with repeated ls, ask, run, debug, and validate commands; agents and automation should use explicit CLI commands or MCP tools. Type exit to quit the REPL.

Optional local defaults live in ~/.semantic_rails/profiles.yml. Run semantic-rails profile init --package-path ./my_package when you want the human CLI to use this package without repeating --path. Keep that file local; it is not package source, deployment config, or cloud tenant config.

3. Optional bundled smoke package
terminal 
semantic-rails packages
semantic-rails ask --package jaffle_shop "revenue by store" --run
semantic-rails catalog --package jaffle_shop

jaffle_shop is a bundled synthetic fixture for smoke testing. It is not a prerequisite for modeling your own data.

3b. Optional HTTP API and MCP server
terminal 
PACKAGE_PATH="$(pwd)/my_package"
semantic-rails mcp setup --path "$PACKAGE_PATH"
managed MCP and client config 
semantic-rails mcp setup --path "$PACKAGE_PATH" --client both --mcp both --install --yes
semantic-rails mcp status --path "$PACKAGE_PATH"
semantic-rails mcp start --path "$PACKAGE_PATH" --port 8091
curl -s http://127.0.0.1:8091/health
semantic-rails mcp stop --path "$PACKAGE_PATH"

Use absolute paths for MCP client configuration because the client may not start in your project directory. From a source checkout, prefix these commands with uv run.

Managed mcp start/status/stop is POSIX-only. On Windows, install the generated config so Claude or Codex launches stdio, or keep semantic-rails mcp http open in a foreground terminal.

HTTP API (separate terminal) 
semantic-rails serve --path "$PACKAGE_PATH" --host 127.0.0.1 --port 8081

semantic-rails serve, semantic-rails mcp stdio, and semantic-rails mcp http are foreground server processes. Run them from a separate terminal or let an MCP client launch stdio from its generated config.

Docker and ASGI make the runtime deployable, but this is not a hosted cloud bundle, managed acceleration layer, or full enterprise auth system.

4. Follow the guided builder path

The preferred public flow is no longer "write raw JSON first." Start with discovery, inspect the semantic object, then ask for the next legal move.

curl 
curl -s -X POST http://127.0.0.1:8081/api/v1/discover \
  -H "Content-Type: application/json" \
  -d '{
    "terms": "revenue by store"
  }'
curl 
curl -s -X POST http://127.0.0.1:8081/api/v1/build-options \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "version": 1,
      "select": [
        {
          "expression": { "measure": "measure.jaffle.revenue_usd" },
          "as": "revenue_usd"
        }
      ]
    },
    "focus_terms": "revenue by store",
    "focus_object_id": "measure.jaffle.revenue_usd",
    "step": "group_by",
    "limit": 6
  }'
5. Run a first query
curl 
curl -s -X POST http://127.0.0.1:8081/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "version": 1,
      "select": [
        {
          "expression": { "measure": "measure.jaffle.revenue_usd" },
          "as": "revenue_usd"
        }
      ],
      "group_by": ["dimension.jaffle_store_name"],
      "time": {
        "temporal_role": "temporal_role.jaffle_order_time",
        "grain": "month"
      },
      "order_by": [{ "field": "revenue_usd", "direction": "DESC" }],
      "limit": 5
    }
  }'

Querying a package outside configs/semantic_rails/

query, compile, validate, and MCP all accept --path <dir>. Use that form for a package created in your own project folder:

path-based package query 
semantic-rails query --path ./my_package --query-json '{
  "version": 1,
  "select": [{ "expression": { "metric": "metric.my_package.total_amount" }, "as": "total_amount" }],
  "limit": 5
}' --verbosity minimal --sql-profile off

The compact flags keep first-run output focused on rows and row counts. Omit them when you want SQL, trace, and explain metadata.

6. Run the test suite
terminal 
uv run pytest -q tests/semantic_rails
What to do next