Telos Brain CLI (brain)

A standalone command-line tool that deploys a Telos Brain from configuration-as-code to the Management API. It reads a brain-compose.yml manifest, parses the referenced skill, workflow, tool and blueprint files, and POSTs them to the API in the correct order.

Status: brain init, brain update, brain deploy, brain snapshot, and brain login are available. brain clone is not implemented yet.

Install

From npm (recommended)

npm install -g @telos.ready/brain
brain --help

Requires Node.js 25+.

From this repository (development)

cd src/telosbrain.cli
npm install
npm run build
npm link   # optional: makes `brain` available on your PATH

During development you can run without building:

npm run dev -- deploy ../../brain-schema --dry-run

Creating a brain folder

Scaffold a local schema from the private starter template ([email protected]:telos-brain/starter-brain.git over SSH — the repo is private):

brain init                 # creates ./brain
brain init my-brain        # creates ./my-brain

Requires working GitHub SSH access (ssh -T [email protected]). Override with --template <url> or TELOS_STARTER_BRAIN_URL (e.g. an HTTPS remote if you prefer).

To upgrade the CLI itself later:

brain update               # npm install -g @telos.ready/brain@latest

Deploying a brain

End-to-end flow for pushing a local brain schema to the Management API.

1. Prepare credentials

Prefer an organisation API key for non-interactive / CI use. An organisation admin mints a key once:

POST /organisations/current/api-keys   { "name": "ci-cd" }

The response contains the full key (tbk_…) once — store it immediately.

Put credentials next to your schema (see brain-schema/.env.example). Destination is controlled by TELOS_BRAIN_API_URL in the chosen env file:

# .env.prod
TELOS_BRAIN_ORG_API_KEY=tbk_...
TELOS_BRAIN_API_URL=https://go.telosbrain.com

# .env.local  (created by brain start from .env.example when missing)
TELOS_BRAIN_ORG_API_KEY=tbk_local_dev_key_do_not_use_in_production_0001
TELOS_BRAIN_API_URL=http://127.0.0.1:60061

Legacy names TELOS_ORG_API_KEY / TELOS_API_URL / TELOS_TOKEN are still accepted.

Or store credentials with the CLI:

brain login --api-key tbk_... --api-url https://go.telosbrain.com

In CI, set TELOS_BRAIN_ORG_API_KEY (and TELOS_BRAIN_API_URL) as secrets instead of committing .env.

2. Deploy

From a folder that contains brain-compose.yml (or pass the path explicitly):

brain deploy --env prod --instance kappa-prod
brain deploy --env local --instance local-brain

--env loads .env.<name> (local | dev | stage | prod). Without --env, the CLI loads .env. brain.lock records instance brain IDs (create vs migrate) and does not choose the destination.

Useful options:

brain deploy ../../brain-schema --env prod --instance kappa-prod --dry-run
brain deploy --instance kappa-prod --api-url https://go.telosbrain.com

Deployment order is enforced: brain → skills → workflows → tools → memory.

3. Snapshot before redeploying (recommended)

If the live brain has moved on (learned versions, remote edits), pull it back before redeploying to avoid version conflicts:

brain snapshot --env prod --instance kappa-prod
brain deploy --env prod --instance kappa-prod

Version conflicts (409) are reported as warnings, not failures — the CLI still applies everything else and exits 0.

Authentication

The CLI supports two credential kinds:

• Organisation API key — the non-interactive credential for npm run and CI/CD. It authenticates as the organisation directly (no person / Clerk sign-in required) and is sent on the X-Telos-Api-Key header. This is the recommended way to deploy.
• Clerk bearer token — the interactive credential, sent on the Authorization header.

Credentials resolve in this order (an organisation API key always wins over a token at the same level):

1. --api-key <key> / --token <token> flags
2. TELOS_BRAIN_ORG_API_KEY / TELOS_BRAIN_TOKEN (legacy TELOS_ORG_API_KEY / TELOS_TOKEN)
3. A .env or .env.<env> file next to the schema's compose file (loaded on deploy / snapshot)
4. Stored credentials at ~/.telos/credentials (written by brain login)

API URL resolves as: --api-url → TELOS_BRAIN_API_URL (legacy TELOS_API_URL) → stored credentials → default http://localhost:5183.

Real environment variables always take precedence over a checked-out .env, so a CI secret overrides the file.

Commands

brain init [path]

Clones the starter-brain template into [path] (defaults to ./brain), then removes the cloned .git folder so the result is a clean scaffold.

| Option | Description | | --- | --- | | --template <url> | Git URL of the starter template. |

brain update

Upgrades the globally installed CLI via npm (@latest, or @beta if this build is a prerelease). Equivalent to npm install -g @telos.ready/brain@latest.

brain deploy [path]

Deploys the brain resolved from [path]:

• If [path] is a .yml file, it is used directly.
• If [path] is a folder (or omitted, defaulting to the current directory), the CLI looks for brain-compose.yml, brain-compose.yaml, brain.yml, then brain.yaml.

| Option | Description | | --- | --- | | --instance <name> | Instance name to deploy to (required on first deploy). | | --name <name> | Name for the brain on first deploy (defaults to the compose name). | | --env <name> | Load .env.<name> (local | dev | stage | prod). Destination comes from TELOS_BRAIN_API_URL in that file. | | --api-key <key> | Organisation API key (overrides TELOS_BRAIN_ORG_API_KEY and the schema .env). | | --token <token> | Clerk bearer token (overrides TELOS_BRAIN_TOKEN and stored credentials). | | --api-url <url> | Management API base URL (overrides TELOS_BRAIN_API_URL). | | --local | Thin helper: if no URL/key is set, use brain.config.toml / the well-known local org key. | | --remote | Thin helper: do not invent a local URL. | | --dry-run | Parse and validate only; make no API calls. |

Instance name. Every brain has an organisation-scoped instance name — a lowercase DNS-style slug (letters, digits and hyphens, 3–63 chars, e.g. kappa-prod). It is defined by the CLI, not the compose file, so the same brain-compose.yml can be deployed to multiple instances (kappa-prod, kappa-staging, …). The instance name is how brains are addressed on the Management API (/brains/{instance}/…) and must be unique within your organisation.

brain.lock is state, not destination. On first deploy for an instance the CLI calls POST /brains, prints the brain ID and API key (shown once), and records the instance in brain.lock next to the compose file. Subsequent deploys migrate that instance. Destination always comes from the env file / flags / credentials — never from brain.lock.local. When a folder tracks exactly one instance, --instance can be omitted.

Related local files: brain.config.toml is Docker stack settings for brain start (ports, image). .env* holds deploy destination and secrets.

brain snapshot [path]

Pulls the live schema for a brain from the Management API and writes every file into [path] (defaults to the current directory). This is a full refresh — existing schema files under the target folder are overwritten with the server versions.

Auth and API URL resolution match brain deploy (flag → env → brain-folder .env → ~/.telos/credentials), with the instance's recorded brain.lock API URL as a fallback.

| Option | Description | | --- | --- | | --instance <name> | Instance to snapshot (defaults to the sole instance in brain.lock). | | --env <name> | Load .env.<name> for credentials (local | dev | stage | prod). | | --api-key <key> | Organisation API key. | | --token <token> | Clerk bearer token. | | --api-url <url> | Management API base URL. |

brain snapshot ../../brain-schema --env prod --instance kappa-prod

brain login

Stores an organisation API key or a Clerk bearer token (and optional default API URL / organisation) at ~/.telos/credentials:

brain login --api-key tbk_... --api-url https://your-management-api

Brain folder format

The compose file references everything else by relative path:

brain-compose.yml        # name, entities, unitsofwork, and paths to the below
skills/<book>/skillbook.yml   → categories → skill markdown (frontmatter + body)
tools/<group>/tools.yml       → tool .yml files (api + parameters)
workflows/*.md                → frontmatter header + markdown instructions
blueprints/<bp>/blueprint.yml → categories + sibling entry markdown files

See ../../brain-schema for a complete worked example.

Publishing

This package is published publicly on npm (@telos.ready/brain).

• README.md (this file) — full developer docs kept in the repo
• docs/npm-readme.md — user-facing docs shown on the npm package page (swapped in at pack/publish time)

npm run publish:dry-run    # review the tarball (includes README.npm.md as README.md)
npm run release:patch      # or release:minor / release:major

See PUBLISHING.md for the full runbook.

Project layout

src/
  index.ts            # commander entry point (bin: brain)
  commands/           # init, update, deploy, snapshot, login
  core/               # compose resolution, starter template URL, file readers
  api/                # Management API client + DTO types (mirror of TelosBrain.Core.Models.Deploy)
  auth/               # credential resolution (org API key / token; .env, env, ~/.telos/credentials)
  state/              # brain.lock read/write
  util/               # logger, errors, version, update check