# Cielara Connector

Two packages, built from this one repo:

- **`cielara`** (Free) — ships the Cielara code-graph sidecar and a thin CLI.
  It auto-enables dependency-aware grep enrichment per repo via a Claude Code
  SessionStart hook that backgrounds `cielara enable`. No MCP server.
- **`cielara-enterprise`** (full) — the superset: everything in Free plus the
  Cielara MCP server (knowledge graph, agent memory, world model), skills, slash
  commands, and grep hooks across 12 AI clients.

Both publish at the same version. Install the one you're licensed for.

## Install (enterprise)

```bash
npm install -g cielara-enterprise
cielara login https://your-cielara.example.com
```

`cielara login <url>` saves the portal URL, runs browser auth, and on success
**automatically runs `cielara install`**: token + license check → writes the
agent-memory MCP server into your AI clients → installs the Cielara skills →
`cielara enable --recursive` (finds every git repo under the current folder and
indexes it via the `cielara-code` sidecar, which also wires its own session +
grep hooks). The connector installs no hooks of its own.

## Install (free)

```bash
npm install -g cielara
cielara login https://your-cielara.example.com
```

The free package ships only the code-graph sidecar. A Claude Code SessionStart
hook backgrounds `cielara enable` to index each repo on demand. No MCP server.

or without a global install:

```bash
npx cielara config set portal-url https://your-cielara.example.com
npx cielara login
npx cielara install
```

`cielara login` opens a browser, runs OAuth authorization-code with PKCE against
the configured portal, and stores non-secret connection metadata in:

```text
~/.cielara/connector.json
```

`cielara install` writes MCP server entries for:

- Codex: `~/.codex/config.toml`
- Claude Code: `~/.claude.json`
- Claude Desktop: platform-specific `claude_desktop_config.json`
- Cursor: `~/.cursor/mcp.json`

The installed MCP command is:

```bash
npx -y cielara mcp
```

The `mcp` command refreshes the stored access token when it is close to
expiration, prepares a Python virtualenv for the bundled MCP server, and then
starts the server in stdio mode.

## Commands

```bash
cielara config set portal-url https://your-cielara.example.com
cielara login
cielara install --target codex
cielara install --target claude
cielara install --target cursor
cielara status
cielara logout
cielara mcp
```

For local development from this repository, write app configs that point at the
checked-out package instead of npm:

```bash
node connector/bin/cielara.js install --local
```

## Configuration

Portal URL defaults:

- `cielara config set portal-url <url>`: set the default portal URL used by
  future `cielara login` runs.
- `cielara config get portal-url`: show the configured portal URL.
- `cielara config unset portal-url`: clear the configured portal URL and return
  to the built-in default.
- `--name <name>`: store a named connection, default `default`
- `--config <path>`: override the credential file path

For the local docker/dev stack, this works from the frontend URL:

```bash
node bin/cielara.js config set portal-url http://localhost:3100
node bin/cielara.js login
```

The portal is responsible for returning the API endpoints and license metadata
used by the CLI after login.

Environment overrides used by the installed MCP server:

- `CIELARA_CONNECTOR_CONFIG`
- `CIELARA_BACKEND_URL`
- `MEMORY_API_URL`
- `WORLD_MODEL_URL`
- `CIELARA_ACCESS_TOKEN`
- `CIELARA_PYTHON`
