@meistrari/tela-cli
v1.15.1
Published
Tela command line tools for local state and agent workflows.
Maintainers
Keywords
Readme
Tela CLI
@meistrari/tela-cli owns the local tela binary for scriptable access to
Tela Local state, Pantry services and skills, agent repositories, and Workflow
Code projects.
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
Run tela help, tela agent --help, tela skills --help, or
tela workflow --help for the authoritative flag list.
Local state, auth, and Pantry services:
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 --jsonManaged Pantry skills:
tela skills list --json
tela skills search <query> --json
tela skills files <slug> --json
tela skills cat <slug> [path]
tela skills install <slug...> --force --no-symlink --ignore-scripts --json
tela skills upgrade [slug...] --ignore-scripts --json
tela skills uninstall <slug...> --ignore-scripts --jsonAgent repository workflows:
tela agent setup --list-options --context <context-id> --organization <id-or-name> --clone-root <path> --dry-run --json
tela agent sync [repo] --current --all --dry-run --json --verbose
tela agent run --input <name=path>... --mode <one-shot|chat> --input-conflict <fail|overwrite|rename> --plain --json --verbose
tela agent push --message <text> --claude --manual --dry-run --json --verbose
tela agent merge [branch] --base <branch> --strategy <squash|merge> --keep-branch --yes --dry-run --json --verbose
tela agent feedback --list --apply <all|select> --feedback-id <id>... --json --verboseWorkflow Code:
tela workflow init --directory <path> --workflow <key>... --package-manager <bun|pnpm|npm|yarn> --yes --json
tela workflow create <target> --project <project-id> --json
tela workflow compile [target] --config <path> --env <path> --json
tela workflow sync [target] --yes --json
tela workflow publish [target] --environment <name> --create-environment-if-missing --yes --json
tela workflow watch [target] --json
tela workflow codegen --json
tela workflow docs [page]tela workflow is routed into @meistrari/workflow-code; see
docs/workflow-code/ for its authoring
API, compiler, and state model. tela workflow docs [page] prints the
user-facing Workflow Code Page documentation bundled with the CLI.
auth login uses device flow and creates or updates a context backed by the
same OS 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 typecheckRun 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 --jsonUse 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 --jsonMCP Clients
tela mcp setup pantry registers the Pantry MCP server in Claude Code and Codex:
tela mcp setup pantry # every client found on PATH
tela mcp setup pantry --claude # Claude Code only
tela mcp setup pantry --codex # Codex only
tela mcp headers pantry # the helper both clients run- Claude Code gets a user-scope
pantryserver withheadersHelper, written throughclaude mcp add-json --scope user. - Codex gets
[mcp_servers.pantry]withhttp_headers_helperin$CODEX_HOME/config.toml(default~/.codex). - Both clients run
tela mcp headers pantryon connect and again after a401, so the access token renews without running the setup again. The helper reads the session of any Production context. telamust be on thePATHof the client process. The setup runs the helper once at the end and fails when it can't.- A local-scope
pantryserver in a Claude Code project takes precedence over the user entry in that project. The setup lists those projects and leaves them alone.
Credential Behavior
The CLI uses the credential adapter contract from local-config.
envcredentials readTELA_ACCESS_TOKEN,TELA_REFRESH_TOKEN, orTELA_DATA_TOKEN.keychaincredentials use the OS keychain: the systemsecuritycommand on macOS, or the freedesktop Secret Service viasecret-tool(libsecret) on Linux. Linux needssecret-toolonPATH(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.- When
DBUS_SESSION_BUS_ADDRESSis unset, as in the cleared environment Codex gives MCP helpers,secret-toolgetsunix:path=$XDG_RUNTIME_DIR/bus, or/run/user/<uid>/bus, when that socket exists. - expired user-session access tokens with a refresh token are reported as
refreshable, not as a hard auth failure. auth tokenrefreshes 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.
mcp headers pantry always prints the token inside the header MCP clients send,
with or without --json. Other commands keep default and --json output
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 testPublished 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 --quietThe 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.tsThis 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.
