Tela CLI

Tela CLI is a one-shot terminal tool for syncing Tela repositories, running local agents, preparing pushes, and applying commit feedback with Claude.

Installation

bun install -g @meistrari/tela-cli

This installs the package globally and adds a tela alias to your ~/.zshrc. After installing, either open a new terminal or run:

source ~/.zshrc

Default command

tela

List workspace repositories that are available to sync locally.

When to use: Run this with no subcommand when you want to see which workspace repositories are available before using tela sync <repo>.

Examples:

• tela — Render the available repositories in a human-readable table
• tela --json — Emit the available repositories as JSON

Version

Examples:

• tela --version — Print the current Tela CLI version
• tela -v — Print the current Tela CLI version

Commands

setup

Configure Tela CLI, sign in with device flow, choose the workspace organization, provision Forgejo access, and verify the local environment

When to use: Run this first on a new machine, or any time your environment target, clone root, Tela session, or SSH key changes.

Examples:

• tela setup — Choose production, staging, or a custom environment, complete browser-based sign-in, select the workspace organization, and provision Forgejo access with an SSH key

sync [repo]

Clone or update a Tela repository, or refresh the current checkout

When to use: Use this before coding to get a clean local checkout, or to refresh every repository under the configured clone root. SSH-backed sync automatically accepts first-seen host keys during clone and update flows.

Examples:

• tela sync agent-api — Clone or update a specific repository under the clone root
• tela sync --current — Sync the repository for the current working directory
• tela sync --all — Refresh every repository directly under the clone root

run

Run the local agent repository with project-scoped Claude

When to use: Use this from inside an agent repository when you want Claude to follow the repo-local contract files, ignore user/global Claude config by default, show its progress live, and produce the expected result artifact.

Examples:

• tela run — Run the current agent repository with project-scoped Claude and the live viewer
• tela run --plain — Force project-scoped execution with scrollback-first text output
• tela run --json — Emit the final project-scoped execution and artifact envelope as JSON

push

Preview, commit, and push the current repository

When to use: Use this after reviewing local changes when you want Tela to stage everything, produce a commit message, and push the branch.

Examples:

• tela push — Choose the commit-message flow interactively
• tela push --claude — Generate a commit message from the current worktree
• tela push --message "Update feedback flow" — Skip prompts and use an explicit commit message

feedback

Guided review of commit feedback with optional Claude handoff

When to use: Use this after pushing or after a feedback-producing commit when you want a guided review of the feedback, a prompt preview before launch, and an outcome summary after Claude exits.

Examples:

• tela feedback --list — Open the guided review flow without launching Claude
• tela feedback --apply all — Preview and launch Claude against every actionable suggestion
• tela feedback --apply select — Choose specific actionable suggestions before launching Claude

status

Show Tela config, session state, tool availability, repo state, and Agent API reachability

When to use: Use this for a quick snapshot of whether the local environment is ready before running mutating commands.

Examples:

• tela status — Render a human-readable environment summary
• tela status --json — Emit a machine-readable status report

doctor

Diagnose config, auth session, tools, filesystem state, repo health, and Agent API reachability

When to use: Use this when Tela fails or behaves unexpectedly and you need exact remediation steps.

Aliases: diag

Examples:

• tela doctor — Run the full diagnostic suite with remediation guidance
• tela doctor --json — Emit structured diagnostic output for scripts

Output modes

• Human output is structured for terminal use with grouped summaries and next actions.
• --json is available on read-heavy flows and on tela run for the final execution envelope.

tela run scope

• tela run loads project-scoped Claude settings by default and excludes user/global Claude config.
• Remaining external inputs are explicit: Claude's built-in system prompt, managed enterprise settings, auth/provider credentials, minimal shell runtime environment, and the default model when agent.config.json does not set one.

First run

1. tela setup
2. tela status
3. tela sync <repo> or tela sync --current
4. tela run
5. tela push
6. tela feedback --list