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

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:

tllt configure

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

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

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

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:

tllt profiles

Authentication

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

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

Workflow

# 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}/… 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 — start here: golden path + gotchas
• docs/commands.md — full command/flag/JSON reference
• docs/schemas.md — how to learn each entity's data model
• docs/authentication.md — basic vs api-key/Cognito
• docs/workflow.md — snapshot layout + diff/deploy semantics
• docs/apis.md — the DO and Scheduler APIs
• docs/scheduler.md — Scheduler's dataTemplate scoping

Commands

| Command | Description | | ----------- | ----------------------------------------------------------------- | | configure | Bootstrap or update a connection (alias: init) | | profiles | List configured connections (alias: connections) | | 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 |