# TilliT CLI

Manage TilliT configuration across the **Digital Operations (DO)** and **Scheduler**
APIs. Built to be friendly for both humans and AI agents: bootstrap a connection once,
then `import` → `diff` → `deploy`.

## Install

```bash
npm install -g @gotillit/tllt      # or run ad-hoc with: npx @gotillit/tllt <command>
```

## First run — bootstrap a connection

A **connection is identified by environment + tenant**, so you can keep several side by
side (e.g. `client1` on prod and `client2` on stage). Profiles are stored in
`~/.tillit/config.json` and named `{tenant}-{environment}`.

Interactive:

```bash
tllt configure
```

Non-interactive (agent-friendly) — basic auth:

```bash
tllt configure --tenant client1 --environment prod \
  --auth basic --username alice --password '••••' --default
```

Non-interactive — API key + secret (Cognito `client_credentials` → bearer token):

```bash
tllt configure --tenant client2 --environment stage \
  --auth apikey --api-key <cognitoClientId> --api-secret <secret> \
  --token-url https://<domain>.auth.<region>.amazoncognito.com/oauth2/token \
  --scopes 'api/*.read,api/*.write'
```

List connections:

```bash
tllt profiles
```

## Authentication

| Method   | How it authenticates                                                            | APIs                  |
| -------- | ------------------------------------------------------------------------------- | --------------------- |
| `basic`  | `Authorization: Basic base64(username@{tenant}.tillit.cloud:password)`          | DO + Scheduler + Wire Flow |
| `apikey` | Cognito `client_credentials` → cached bearer token; `tillit-tenant` header set  | DO + Scheduler + Wire Flow |

Tokens obtained via `apikey` are cached in `~/.tillit/tokens.json` until shortly before
they expire.

## Workflow

```bash
# 1. Snapshot the live configuration into ./{profile}/ (the current directory)
tllt import --profile client2-stage         # use --dir <path> to write elsewhere

# 2. Compare two snapshots (desired -> target) and review the changeset
tllt diff --from client2-stage --to client1-prod

# 3. Apply the difference to the live target
tllt deploy --from client2-stage --to client1-prod --dry-run   # preview
tllt deploy --from client2-stage --to client1-prod             # apply (asks to confirm)
tllt deploy --from client2-stage --to client1-prod --prune -y  # also delete extras, no prompt
```

Snapshots are written to the **current directory** (override with `--dir`), so you can keep
config in its own git repo. They live under `./{profile}/{api}/{Entity}/…` as `.rdata` records, with a `_meta.json` per entity
recording how to route writes. Volatile fields (`id`, `createdAt`, `updatedAt`) are
stripped on import, so a content difference reflects a real configuration change. Records
are matched across environments by their natural key (the `name`, used as the filename).

## Agent-friendly notes

- Add `--json` to any command for machine-readable output on **stdout** (progress goes to
  stderr). Errors are emitted as `{ "ok": false, "error": "…" }` with a non-zero exit code.
- All commands are fully flag-driven — no interactive prompts when the required flags are
  supplied. Set `TILLIT_JSON=1` to force JSON mode.
- `--profile <name>` selects a connection; otherwise the default profile is used.

## Documentation (for humans and AI agents)

Agent-readable guides live alongside the code:

- [`AGENTS.md`](AGENTS.md) — start here: golden path + gotchas
- [`docs/commands.md`](docs/commands.md) — full command/flag/JSON reference
- [`docs/schemas.md`](docs/schemas.md) — how to learn each entity's data model
- [`docs/authentication.md`](docs/authentication.md) — basic vs api-key/Cognito
- [`docs/workflow.md`](docs/workflow.md) — snapshot layout + diff/deploy semantics
- [`docs/apis.md`](docs/apis.md) — the DO and Scheduler APIs
- [`docs/scheduler.md`](docs/scheduler.md) — Scheduler's dataTemplate scoping

## Commands

| Command     | Description                                                       |
| ----------- | ----------------------------------------------------------------- |
| `configure` | Bootstrap or update a connection (alias: `init`)                  |
| `profiles`  | List configured connections (alias: `connections`)               |
| `schema`    | Describe an entity data model (fields, types, required, enums)    |
| `import`    | Snapshot a connection's current configuration into local files     |
| `diff`      | Compare two snapshots and show the changeset                      |
| `deploy`    | Apply the difference between two snapshots to the live target     |
| `api`       | Authenticated pass-through call to the tenant APIs                |
| `check`     | Read-only tenant integrity checks (duplicates, ghosts, collisions)|
| `rename`    | Rename a record id-preservingly, keeping every FK intact          |
| `wireflow`  | Manage BPMN workflows (list, pull, push, validate, activate)      |
| `install`   | Install the tllt skill into Claude Code                           |

---

## Using with Claude Code

`tllt` is built to work as a tool for AI agents. The fastest way to get started
is through [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (CLI or
desktop app) — Claude can install, configure, and drive `tllt` autonomously.

### Quick start

Open Claude Code and ask:

> Install @gotillit/tllt globally and configure a connection to my TilliT tenant.

Claude will run:

```bash
npm install -g @gotillit/tllt
tllt configure          # interactive — Claude walks you through it
```

That's it. From here you can ask Claude to import, diff, and deploy configuration
using natural language.

### What Claude can do with tllt

- **"Import the config from client1-prod"** — snapshots the live tenant to local files
- **"Diff stage against prod and summarise what's different"** — runs `tllt diff` and explains the changeset
- **"Deploy stage config to prod, dry-run first"** — previews then applies changes with confirmation
- **"Show me the schema for Operation"** — describes the entity data model
- **"Rename the route 'Old Name' to 'New Name'"** — id-preserving rename across all FKs
- **"Run an integrity check on the tenant"** — finds duplicates, ghost records, collisions
- **"Call GET /operations and filter by status"** — ad-hoc API calls with auth handled

### Prerequisites

Claude Code needs **Node.js ≥ 18** available in its shell.

**macOS:**
```bash
brew install node       # or: nvm install 20
```

**Windows:**
```powershell
winget install OpenJS.NodeJS.LTS       # or download from https://nodejs.org
```

**Linux:**
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs
```

### Tips

- All commands support `--json` for structured output — Claude uses this
  automatically to parse results reliably.
- Credentials are stored locally in `~/.tillit/config.json`. Claude can set up
  multiple profiles for different tenants/environments.
- Point Claude at [`AGENTS.md`](AGENTS.md) if it needs deeper context on
  gotchas, deploy semantics, or scheduler-specific behaviour.