CLI command reference

The tama binary is the command-line program you install on a machine to connect it to Task Machine and run a local worker. It groups two kinds of commands: the ones a person runs to set up and operate a machine — setup, version, status, update, workers, daemon, and the startup helpers — and the resource commands an agent's worker uses on its behalf during a task. This page lists the real command tree, its arguments, and its flags. For the bigger picture of how machines fit the product, see worker machines. To install the binary, see getting started.

Every command reads its configuration from ~/.taskmachine/config.json, written by tama setup. A machine connected by an older release that wrote to the legacy path ~/.config/taskmachine/config.json keeps using that file until it is reconnected. Commands that connect to Task Machine refresh the stored access token automatically when it has expired, and fall back to asking you to run tama setup again when the stored credentials can no longer be refreshed.

Operator commands

These are the commands a person runs to connect a machine and keep its worker reporting.

tama setup

tama setup connects this machine to one or more Task Machine workspaces. It opens a browser, asks you to approve the machine and choose which workspaces it may access, then saves the issued tokens and the selected workspaces to the local config file. Run interactively, it then asks whether to start the daemon automatically when you log in — installing the startup entry on yes — and starts the daemon either way, so the workspace sees the machine connected the moment setup finishes. Run non-interactively, it performs one sync itself and prints the tama daemon install-startup reminder instead. When a daemon is already running, setup stops it before saving the new connection and starts it again afterwards.

tama status

tama status prints a health report for this machine: the app URL, CLI version, whether the daemon is running, and whether the server is reachable, followed by each connected workspace's machine id, status, last heartbeat, execution root, and the coding tools it offers. Local state prints even when the server is unreachable or the stored credentials have expired — those show up as a labeled server line (including the tama setup command to reconnect) with the per-workspace detail degraded rather than the command failing. If the access token has expired, the CLI refreshes it automatically first. Use it as the first check after setup or when a machine looks offline.

tama version

tama version prints the installed CLI version.

tama update

tama update installs the current trusted Task Machine CLI release. It verifies the download, chooses the matching operating system and architecture binary, and replaces the local executable only after those checks pass. On Windows, the update is staged and the executable is replaced as soon as the current tama process exits, because Windows keeps a running .exe locked.

tama workers

tama workers prints a table of the coding tools detected on this machine, including the ones that are missing, with each tool's provider, availability, executable path, and version or the reason it was not found. The table adapts its columns to the terminal width. This command reads only the local machine — it does not contact Task Machine — so it is the fastest way to confirm a tool is on PATH before connecting.

tama daemon

tama daemon starts the long-running loop that keeps the machine and its workers reported to Task Machine. It detects the supported tools on PATH, sends a heartbeat on a fixed interval, reports any skills and agent definitions it discovers locally, and runs work Task Machine assigned to workers that are enabled for agents. It runs until interrupted. When it runs in the background, its output is written to ~/.taskmachine/daemon.log, which the daemon keeps from growing without bound. The subcommands manage the running daemon and automatic startup:

Startup definitions are platform-specific, so the daemon resolves the right form for the current operating system.

tama exec

tama exec <executable> [args...] runs a child process and streams its standard output and standard error to your terminal. It takes at least one argument — the executable — followed by any arguments to pass through. Task Machine uses this same process behavior to run local tools and capture their output during a task.

Agent resource commands

The remaining commands act on workspace records on behalf of a single agent. A worker invokes them while executing a task so the agent can read context and post its work back through the same audit trail a person uses. Manual runs must identify the acting agent with --agent or TAMA_AGENT_MEMBERSHIP_ID. The workspace may resolve from --workspace, TAMA_WORKSPACE_ID, or the machine's connected-workspace config, so pass --workspace only when that resolution is missing or ambiguous. Inside a worker run you usually omit --agent, because the worker fills it from the job it is already running, and you usually omit --workspace too when the job exported TAMA_WORKSPACE_ID. Commands that write a body read it from standard input, and commands that take structured input read JSON from standard input. Results are printed as pretty JSON.

tama tasks

tama tasks reads and updates tasks as an agent.

assign takes exactly one of --assignee or --team. --assignee names one workspace member, human or agent. --team queues the task with one team. --reason is optional context for why the task should move. The result always includes status, task, timeline_event_id, and inbox_item_ids. "status": "applied" means the assignment changed immediately. "status": "pending" means a human approval is required first, so the task has not moved yet and inbox_item_ids tells you which inbox items were created.

subtasks create reads a JSON object from standard input. title is required. description, status, priority, assignee_membership_id, and subtask_position are optional. The result always includes status, timeline_event_id, and inbox_item_ids. subtask is present only when the creation applied immediately.

{
  "title": "Draft the incident timeline",
  "description": "Pull the deploy and log timestamps into one note.",
  "priority": 2,
  "assignee_membership_id": "mem_123"
}

tama workflows

tama workflows starts an existing workflow definition under one task when the task should move through a repeatable process instead of a one-off follow-up.

start is task-scoped even though it sits in its own top-level command group. --task is required. Standard input is optional and must be a JSON object when present. Blank standard input omits input entirely. The result always includes status, timeline_event_id, and inbox_item_ids. When "status": "applied", the response also includes workflow_run. When "status": "pending", no run exists yet because a human approval is still required.

{
  "release": "candidate",
  "notify": true
}

tama reactions

tama reactions adds or removes an emoji reaction on a comment, so an agent can acknowledge a comment instead of posting a noise reply. A reaction on another agent's comment can also steer that agent when the reacting agent's profile allows it: 👍 tells the agent to proceed, 👎 tells it to stop or adjust, and 👀 acknowledges without necessarily asking for more work. The supported emoji are 👍, 👎, and 👀.

tama goals

tama goals reads goals visible to the agent.

tama budget

tama budget lets an agent see the budgets that bound its work and ask for more room before it hits a ceiling. See budgets and retries for how those limits are enforced.

request-increase requires --rationale and at least one requested limit that is higher than the current one: --amount for the cost ceiling and --input-tokens, --output-tokens, and --cache-write-tokens for the token limits. The request does not change the limit — it lands in the inbox for the members who manage budgets to approve or reject. For a goal or team budget the acting agent must lead that goal or team. Budgets on the workspace, a project, a task, an agent, or a workflow are open to any agent in scope.

tama secret

tama secret lets an agent browse and use the workspace vault without ever seeing a sealed value. The agent references a credential by @<name-or-id>; the value is decrypted only at the point of use and injected into a child process, never into the agent's output, prompt, or transcript.

exec takes one or more reference flags — --username @ref, --password @ref, --totp @ref, and --secret NAME=@ref — and injects each into the child process. By default a value is written to a 0600 file on tmpfs whose path is exported as TAMA_SECRET_<NAME>_FILE (the name upper-cased); passing --as-env NAME delivers that value in a plain environment variable NAME instead. The child's output is scrubbed of any resolved value, and the value never reaches the agent's own stdout. If the agent has not been granted access the command does not run and exits non-zero — a human approves the request first.

get resolves a single field and prints only its raw value (nothing else) to stdout, so it can be captured with shell command substitution — for example curl -u "admin:$(tama secret get --field password @db)" … — letting a value flow into a command the agent runs without ever appearing in its own output. It is the escape hatch for when a value must pass through a shell the agent controls; exec, which keeps the value off the terminal entirely, is preferred. On a missing grant get prints no value, writes a message to stderr, and exits non-zero so the substitution fails safe rather than injecting an empty string.

Like the other agent resource commands these accept --agent, --workspace, and (for list/search) --limit, all of which are auto-filled inside a worker run, so an agent normally omits them.

tama documents

tama documents reads documents visible to the agent.

tama artifacts

tama artifacts reads and writes the artifacts an agent produces.

create requires --content-path and --title, and also accepts --content-type, --checksum, and --task to record where the artifact came from. update accepts --content-type and --checksum.

tama memory

tama memory inspects and edits one agent's memory — the bounded markdown note the agent carries between runs.

These commands take --workspace but not --agent. The agent is the positional argument.

tama agents

tama agents carries an agent's self-service commands — the ones an agent runs about its own work rather than about a workspace record.

tama teams

tama teams lets a lead agent route its team's queue.

tama playbooks

tama playbooks lets an agent inspect the code-defined playbook catalog before it proposes new workspace structure by hand. The catalog commands are read-only, permission-scoped to the acting agent, and return the bundles with their requirements, config fields, and the records they would install.

Both commands accept --category, repeated --contains <kind> filters such as workflow, agent, or schedule, and --limit.

tama chats

tama chats lets an agent manage the chat it is running in.

A new chat opens with a placeholder title taken from its first message, so an agent renames it on its first turn to something that captures the conversation. The workspace, agent, and chat default from the worker's TAMA_WORKSPACE_ID, TAMA_AGENT_MEMBERSHIP_ID, and TAMA_CHAT_CONVERSATION_ID environment variables. --workspace, --agent, and --chat override them. Only the chat's own agent may rename it.

tama propose

tama propose <kind> creates an agent-authored proposal for a workspace change, reading the proposed record's attributes as JSON from standard input. Every proposal requires --agent (the proposing agent) and --rationale, and accepts --workspace. A proposal does not apply the change. It surfaces for a person to approve. The JSON-backed kinds are team, agent, skill, mcp, task, project, goal, and workflow.

tama propose connector <catalog-slug> is the setup-first path for a service in the curated connector catalog. It needs no JSON body: Task Machine resolves the current command or remote URL through the official Model Context Protocol registry, then creates an ordinary connector proposal without accepting credentials. When an agent reaches work that needs a missing service, it proposes this setup before attempting the dependent work, waits for approval, account authorization, and assignment, then continues once the connector is available.

Task and project proposal payloads can include goal_id when the agent is leading that goal. A goal-linked task becomes active under the goal when approved, and a goal-linked project receives its goal assignment on approval rather than appearing in the goal before a person decides.

Use tama propose mcp only for a custom server outside the curated catalog. Describe its shape with fields such as name, server_type, command, and args, and leave secret environment values and auth material out of the proposal payload. A skill proposal carries reusable instructions. It does not replace a missing connector or service authorization.

tama propose playbook --from <workflow> is the one proposal with its own shape: it proposes promoting a proven workflow into a reusable playbook, so it requires --from naming the workflow to promote alongside --agent and --rationale.

tama propose bundle <bundle-slug> proposes installing a ready-made playbook as one unit. Put optional install inputs such as project_id and config in the JSON body on standard input. Approving the proposal installs the whole bundle transactionally. Rejecting it creates nothing.

tama propose generated-playbook is the catch-all for when no catalog playbook fits: instead of naming a slug, the agent designs a playbook from scratch and sends the whole playbook — its slug, name, agents, documents, goals, workflow, and schedule — as a JSON map on standard input. It records the same one-unit pending installation a catalog-playbook proposal does, so approving installs every record transactionally, and the proposal renders inline in the chat for approve-or-refine.

From here

For how these commands fit together when a machine comes online and picks up work, read worker machines. The agent resource commands enforce the same role boundaries a person is held to — see permissions reference for the catalog. To choose where local agent work is stored and how the daemon starts, see getting started.