Tela CLI

@meistrari/tela-cli owns the local tela binary for scriptable access to Tela Local state and agent workflows.

The CLI reads and writes the same ~/.tela/config.json state as Tela Dock through @meistrari/tela-local-config. It should not parse local config files directly, and normal output must not print token material.

Commands

Canonical commands:

tela auth login --no-interactive
tela auth logout --context <context-id>
tela auth whoami --json
tela auth token --json
tela auth token --raw
tela context current --json
tela context list --json
tela context show <context-id> --json
tela context use <context-id>
tela env list --json
tela service update --json
tela service list --json
tela service show <slug> --json
tela service api <slug> <METHOD> <PATH> [args...] --service-env <slug> --body <json> --pretty
tela service docs endpoints <slug> --pretty
tela service docs reference <slug> [METHOD PATH|file-path] --pretty
tela service docs guide <slug> [path]
tela service env list <slug> --pretty
tela service env use <slug> <environment>
tela doctor auth --json
tela agent sync [repo] --current --all --dry-run --json --verbose
tela agent run --input <name=path>... --plain --json --verbose
tela agent push --message <text> --claude --manual --dry-run --json --verbose
tela agent feedback --list --apply <all|select> --json --verbose

auth login uses device flow and creates or updates a context backed by the same Keychain credential adapter as Dock. auth token may refresh that session before returning metadata or printing a raw token. On macOS, renewing a Keychain session is delegated to Tela Dock, so sandboxed agents only read the saved credential. The CLI opens the installed Dock in the background if needed; update both Dock and the CLI to use this flow. A valid access token can still be read without Dock. TELA_HOME must refer to the same configuration as Dock.

The top-level api, docs, update, whoami, and token aliases on tela remain available during migration. Service catalog and per-service environment defaults live in validated TELA_HOME/inventory.json, with a dual-read path for the former ingredients.json files. Credential material continues to come from the selected Tela context.

Development

From the repository root:

pnpm cli:build
pnpm cli:test
pnpm --filter @meistrari/tela-cli run typecheck

Run the built binary directly during development:

node apps/tela-cli/dist/index.js context current --json
node apps/tela-cli/dist/index.js auth token --json

Use TELA_HOME to point the CLI at an isolated config directory:

TELA_HOME=/tmp/tela-home node apps/tela-cli/dist/index.js env list --json

Credential Behavior

The CLI uses the credential adapter contract from local-config.

• env credentials read TELA_ACCESS_TOKEN, TELA_REFRESH_TOKEN, or TELA_DATA_TOKEN.
• keychain credentials use the OS keychain: the system security command on macOS, or the freedesktop Secret Service via secret-tool (libsecret) on Linux. Linux needs secret-tool on PATH (Arch: sudo pacman -S libsecret, Debian/Ubuntu: sudo apt install libsecret-tools) and a running Secret Service such as gnome-keyring or kwallet; otherwise the adapter reports a clear diagnostic instead of a token.
• expired user-session access tokens with a refresh token are reported as refreshable, not as a hard auth failure.
• auth token refreshes expired user-session access tokens when a refresh token is available. For macOS Keychain sessions, Dock performs both the exchange and persistence. If Dock is unavailable or too old, the command fails before trying a direct refresh in the CLI; it never silently falls back to the sandbox write that could consume and lose a rotating refresh token.
• unsupported providers report diagnostic status instead of exposing secrets.

auth token --raw is the explicit token-export escape hatch for shell scripts. Default and --json output stay redacted.

Tests

Tests are strict TypeScript black-box node --test cases that execute the compiled CLI with an isolated TELA_HOME. Node strips the test-only types at runtime; consumers do not need a TypeScript runtime.

pnpm --filter @meistrari/tela-cli run test

Published skill installer

scripts/install-skills.ts is the source for the postinstall skill sync. release:prepare bundles it deterministically with esbuild into scripts/install-skills.cjs, then copies that CJS artifact into the publish directory. The generated artifact is kept in the workspace so a fresh workspace install and an npm consumer both run plain Node through:

node scripts/install-skills.cjs --quiet

The published package does not require tsx, TypeScript, or esbuild at postinstall time.

Native macOS renewal regression

After corepack pnpm cli:build, run:

corepack pnpm exec tsx scripts/verify-session-renewal-macos.ts

This uses a disposable Keychain item and a local auth fixture. It reproduces Operation not permitted with sandbox-exec, proves the old path consumed a refresh token before failing to save, then runs the compiled CLI under the same restriction against Dock's broker implementation. It verifies persistence in real Keychain, another expired session, and three concurrent CLI processes. The fixture deletes its Keychain item and temporary config afterward.