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 runtime. It groups two kinds of commands: the ones a person runs to set up and operate a machine — setup, version, status, update, runtimes, daemon, and the startup helpers — and the resource commands an agent's runtime 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 the daemon fits the product, see runtime, machines, and the daemon; to install the binary, see install the CLI.

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 runtime 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. After approval it immediately reports the machine and the runtimes it detected, so the workspace sees the machine the moment setup finishes.

Flag	Default	Purpose
--api-url	https://app.taskmachine.io	Use a support-provided Task Machine app URL during setup.

tama status

tama status checks that the machine can connect to Task Machine with its stored credentials and prints ok when the connection is healthy. If the access token has expired, the CLI refreshes the token and retries before reporting failure. Use it as a quick connectivity 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. Windows binaries can be installed with the hosted installer, but self-update from a running Windows executable is not supported yet.

Flag	Default	Purpose
--check	false	Check whether an update is available without installing it.
--release-url	latest Task Machine release metadata URL	Override the update metadata URL for support and testing.
--target-version	latest release	Install a specific tama version.

tama runtimes

tama runtimes 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 runtimes 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 runtimes that are enabled for agents. It runs until interrupted. The two subcommands manage automatic startup:

Command	Purpose
tama daemon install-startup	Install a startup definition so the daemon launches automatically when the device boots, and print the path of the installed file.
tama daemon uninstall-startup	Remove the startup definition and print the path of the removed file.

Startup definitions are platform-specific; 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. Runtime adapters use 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 runtime 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. Every one of these commands requires --agent with the acting agent's id, and accepts --workspace to pick a workspace by id or slug when the machine is connected to more than one. Commands that write a body read it from standard input; commands that take structured input read JSON from standard input. Results are printed as pretty JSON.

Flag	Required	Purpose
--agent	yes	The agent the command acts as.
--workspace	when more than one is connected	Workspace id or slug.
--query	no	Search text for list commands.
--limit	no (default 20)	Maximum results for list and search commands.

tama tasks

tama tasks reads and updates tasks as an agent.

Command	What it does
tama tasks list	List tasks visible to the agent, optionally filtered by --query.
tama tasks search <query>	Search visible tasks for the given text.
tama tasks show <task-id>	Show one task with its detail.
tama tasks update <task-id>	Update a task from a JSON object on standard input. Setting status to blocked requires a block_reason explaining what the task is waiting for, which is recorded as a comment.
tama tasks spec <task-id>	Write the task's planning spec from a JSON object on standard input — spec (required), acceptance_criteria, spec_assessment, and the four 0-2 review scores (spec_blast_radius_score, spec_novelty_score, spec_sensitivity_score, spec_reversibility_score).
tama tasks summary <task-id>	Write a task completion summary from standard input.
tama tasks review <task-id> --verdict <approve|revise|rethink>	Record the calling reviewer's verdict on a task, reading the notes from standard input.
tama tasks recheck <task-id> --comment <reason> (--in <duration> | --at <time>)	Block the task on an outside wait and schedule one recheck at the chosen time; the comment is required.
tama tasks comment <task-id>	Create a root task comment from standard input.
tama tasks progress <task-id>	Record a progress report from standard input.
tama tasks no-action <task-id>	Record that the agent deliberately took no action this turn, with the reason from standard input.
tama tasks question <task-id> --assignee <id>	Ask a human a question on the task; the assignee is required.
tama tasks approval <task-id> --assignee <id>	Request a human's approval, reading the request body from standard input.
tama tasks dependencies add <task-id> <blocking-task-id>	Add a blocking-task dependency.
tama tasks dependencies remove <task-id> <dependency-id>	Remove a task dependency.

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 👀.

Command	What it does
tama reactions add <comment-id> <emoji>	React to a comment; adding a reaction you already placed is a no-op.
tama reactions remove <comment-id> <emoji>	Remove your own reaction from a comment.

tama goals

tama goals reads goals visible to the agent.

Command	What it does
tama goals list	List visible goals, optionally filtered by --query.
tama goals search <query>	Search visible goals for the given text.
tama goals show <goal-id>	Show one goal.

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.

Command	What it does
tama budget list	List the active budgets in scope, each with its spend, limit, period, and status. Narrow the list with --scope-type and --scope-id.
tama budget show <budget-id>	Show one budget with its current spend and status.
tama budget request-increase <budget-id> --rationale <why>	Ask a human to raise a budget's limit.

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 documents

tama documents reads documents visible to the agent.

Command	What it does
tama documents list	List visible documents, optionally filtered by --query.
tama documents search <query>	Search visible documents for the given text.
tama documents show <document-id>	Show one document.

tama artifacts

tama artifacts reads and writes the artifacts an agent produces.

Command	What it does
tama artifacts list	List visible artifacts, optionally filtered by --query.
tama artifacts search <query>	Search visible artifacts for the given text.
tama artifacts show <artifact-id>	Show one artifact.
tama artifacts create --content-path <id> --title <title>	Create an artifact, reading its body from standard input.
tama artifacts update <artifact-id>	Append a new artifact version, reading its body from standard input.

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.

Command	What it does
tama memory show <agent-id>	Print the agent's memory body, or (no memory) when it is empty.
tama memory write <agent-id>	Replace the agent's memory body with standard input.
tama memory tidy <agent-id>	Propose a deduped, consolidated memory for a human to accept or discard; prints the proposed list and what it would change.
tama memory clear <agent-id>	Delete the agent's memory.

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.

Command	What it does
tama agents question --target <where>	Raise a self-improvement question from standard input. --target is required and chooses where the answer routes — memory or instructions — and --task optionally attaches the question to a task for context.

tama teams

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

Command	What it does
tama teams queue <team-id>	List the tasks queued for the lead agent's team.
tama teams route <team-id> <task-id> --assignee <id>	Route a queued team task to a team member.
tama teams route-thread <team-id> <comment-id> --assignee <id>	Route a team comment thread to an agent teammate.

tama templates

tama templates lets an agent inspect the code-defined template 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.

Command	What it does
tama templates list	List template bundles visible to the agent.
tama templates search <query>	Search bundles by job text, category, and contents.

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.

Command	What it does
tama chats rename <title>	Rename the current chat to a short title.

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 runtime'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 supported kinds are team, agent, skill, mcp, task, project, goal, and workflow.

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.

MCP server proposals should describe the server shape only, such as name, server_type, command, and args. Leave secret environment values and auth material out of the proposal payload.

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

tama propose bundle <bundle-slug> proposes installing a ready-made template bundle 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-bundle is the catch-all for when no catalog bundle fits: instead of naming a slug, the agent designs a bundle from scratch and sends the whole bundle — 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-bundle 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 runtime, machines, and the daemon. 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 install the CLI.