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.

The operator commands read their 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 use the saved connection restore it automatically when possible and ask you to run tama setup again when the machine must be reconnected.

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 connection and selected workspaces to the local config file. Run interactively, it then asks whether to start Task Machine on your computer automatically when you log in — installing the startup entry on yes — and starts Task Machine 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 Task Machine is already running, setup stops it before saving the new connection and starts it again afterwards.

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

tama status

tama status prints a health report for this machine: the app URL, CLI version, whether Task Machine on your computer 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 saved connection needs renewal, the CLI handles that 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 installed CLI only after those checks pass. On Windows, the update is staged and the installed file is replaced as soon as the current tama process exits, because Windows keeps a running .exe locked.

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, including an older one to roll back.

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, installed command 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 Task Machine on your computer and keeps the machine and its workers reported. It detects the supported tools on PATH, sends a heartbeat on a fixed interval, reports up to 500 skills and agent definitions from each local discovery scan, 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 Task Machine keeps from growing without bound. The subcommands manage the running process and automatic startup:

Command	Purpose
tama daemon stop	Stop Task Machine on your computer, however it was started, and confirm it exited.
tama daemon install-startup	Install a startup definition so Task Machine launches automatically when you log in, start it now, and on Linux enable lingering so it survives logout.
tama daemon uninstall-startup	Remove the startup definition and stop Task Machine on your computer, reporting what actually existed.

Startup definitions are platform-specific, so Task Machine chooses the right form for the current operating system.

tama exec

tama exec <command> [args...] runs a child process and streams its standard output and standard error to your terminal. It takes at least one argument — the command — 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 resource commands act on workspace records in an agent context. Task Machine makes them available during agent work, and authenticated operators can invoke them directly. Many commands share a few flags when they apply, but those flags are not universal: tama memory uses a positional <agent-id>, proposal-creation commands do not expose --agent, and some commands expose neither search flag. --workspace selects a configured workspace by id or slug, while --agent selects an agent when the command exposes it. During an agent run, Task Machine keeps both values within that run's authorized scope. Commands that write a body read it from standard input, and commands that take structured input read JSON from standard input. JSON-returning commands print pretty JSON. tama tasks attachments download is the explicit raw-byte standard-output exception.

Common flag	When it appears	Purpose
--agent	Commands that act in an agent context	Select the agent. During a run it must match that run's authorized agent.
--workspace	Commands that select workspace scope	Select a configured workspace by id or slug. During a run it must match that run's authorized workspace.
--query	list commands that support search text	Search text for list commands.
--limit	list and search commands that cap or paginate results	Maximum results for list and search commands.
--after	list and search commands that paginate results	Continue from one page cursor returned by the previous page.

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, and return a page envelope with tasks, next_cursor, and has_more.
tama tasks search <query>	Search visible tasks for the given text and return that same page envelope.
tama tasks show <task-id>	Show one task and return its detail envelope. Up to twenty newest pending_approvals appear first, followed by task, task attachments, dependencies, comments, reviews, timeline, questions, and the complete immutable approval_requests history. Returned attachment url values remain limited to the authorized run. When an attachment preview is absent or truncated, download the raw bytes with tama tasks attachments download <task-id> <attachment-id>.
tama tasks update <task-id>	Update a task from a non-empty JSON object on standard input. Supported fields are title, description, goal_id, git_repository_id, status, priority, due_on, due_at, scheduled_for, recurring_cron, recurring_timezone, schedule_timezone, started_at, completed_at, cancelled_at, label_ids, and block_reason. Setting status to blocked requires a nonblank block_reason, which is recorded in the task event without creating a comment.
tama tasks assign <task-id> (--assignee <id> | --team <id>) [--reason <text>]	Set one workspace member, human or agent, as the task's implementer, or queue it with one team. Exactly one target is required. The JSON result reports whether it applied immediately or is waiting for approval.
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 agent's active task-review verdict, whether it is the implementer pre-review before a human decision or the assigned agent final review. Notes are read from standard input.
tama tasks pull-request link <task-id> --url <url> --head-sha <sha> --title <title> --head-branch <branch> --summary <summary> --changed-files <count> --additions <count> --deletions <count> --ci-status <status> --merge-status <status>	Link one source pull request and report the decision context for its current commit. CI status is pending, passing, failing, or unknown. Merge status is mergeable, conflicting, or unknown.
tama tasks pull-request report <task-id> --url <url> --head-sha <sha> --state <open|closed|merged> [review context flags]	Report the source state and current commit. Repeat the review-context flags after each push because a new commit clears the earlier summary. Use --source-review-required and --source-review-state when repository rules require separate source-host approval.
tama tasks pull-request ready <task-id> --url <url> --head-sha <sha>	Mark the exact open commit ready only after all required CI checks pass and the source reports it mergeable.
tama tasks pull-request review <task-id> --url <url> --head-sha <sha> --verdict <approve|request_changes>	Record the calling agent's active exact-head decision, whether it is the implementer pre-review before a human decision or the assigned agent final review, with optional attributed --notes. Human final reviewers use the Inbox instead.
tama tasks pull-request merge-check <task-id> --url <url> --head-sha <sha>	Check Task Machine approval and any separately required source-host approval immediately before merge.
tama tasks recheck <task-id> --comment <reason> (--in <duration> | --at <time>)	Block the task on an outside wait and set its first recheck time. The reason value is required and is recorded in the task event, not as a comment. If the task remains blocked, later checks follow Task Machine's automatic backoff until the recheck is cleared or the task leaves Blocked.
tama tasks comment <task-id> [--parent-comment <comment-id>] [--option <reply>]... [--attach <path>]...	Create a root task comment or thread reply from standard input. Repeat --option up to five times to offer editable suggested replies, and repeat --attach to add files.
tama tasks progress <task-id>	Request one concrete human action from standard input; the body must tag its single owner.
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> [--option <answer>]...	Ask a human a question on the task. The assignee is required. Repeat --option up to five times to offer predefined answers in their displayed order.
tama tasks approval <task-id> --assignee <id> --deduplication-key <key> [--subject-reference <type>:<id>]... [--context-comment <comment-id>]	Request a human's approval, reading the request body from standard input. Reuse the stable lowercase key when retrying or replacing the same logical decision. Repeat --subject-reference to identify additional records under review; the command always includes the owning task. Optionally bind one explicitly selected task comment as Inbox context.
tama tasks attachments download <task-id> <attachment-id>	Write one task or comment attachment's raw bytes to standard output. Use it when the preview in tama tasks show is absent or truncated, and redirect the output into a file when you need to inspect the full attachment locally.
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 tasks subtasks create <task-id>	Create a delegated subtask from a JSON object on standard input. The JSON result reports whether the subtask was created immediately or parked behind approval.

list and search both accept --limit and --after <cursor>. They return a JSON page envelope shaped like { "tasks": [...], "next_cursor": "..." | null, "has_more": true | false }. When has_more is true, continue with the same search text or the same --query value plus --after <next_cursor>. Cursors are tied to that exact query context, so if you change the query you start again from the first page instead of reusing an older cursor.

update only accepts that generic field set. Nullable string fields are description, goal_id, git_repository_id, due_on, due_at, scheduled_for, recurring_cron, recurring_timezone, schedule_timezone, started_at, completed_at, and cancelled_at. status must be one of backlog, todo, in_progress, in_review, blocked, done, or cancelled. priority must be an integer from 0 through 4. label_ids must be null or an array of label ids. block_reason must be a nonblank string and only belongs with "status": "blocked". Assignment fields, recheck_at, spec fields, summary fields, review fields, dependency fields, and comment fields use their dedicated commands instead of update.

comment reads the comment body from standard input. --parent-comment makes it a reply in that comment's thread. Each repeated --option adds one short suggested reply, and Task Machine shows those suggestions in the order supplied when this is the latest agent comment in the thread. The human can select one to fill the existing composer, edit it, add an attachment, or type something different. Selecting an option never submits the reply automatically. Suggested replies do not notify a person by themselves, so the comment must mention each human who needs to act.

approval uses --deduplication-key as the durable identity of one decision, independent of the request wording. A repeated request with the same key and context reuses the pending approval. Changed wording, scope, capability, or subject replaces it while retaining the earlier request as history. Subject-reference types are task, comment, task_attachment, task_plan_revision, task_pull_request, workflow_run, workflow_run_node_result, and document.

question reads the question from standard input. Each repeated --option adds one short predefined answer, and Task Machine shows those answers in the order supplied. They are suggestions rather than a closed questionnaire. The human can select one for review, edit it, or type a free-text answer when none fits. Selecting an option never submits the answer automatically.

printf '%s\n' 'Which launch window should the first brief use?' | \
  tama tasks question TAS-42 --assignee mem_123 \
  --option 'Publish Tuesday morning' \
  --option 'Wait for Friday interviews' \
  --option 'Start with a smaller pilot'

assign takes exactly one of --assignee or --team. --assignee names one workspace member, human or agent, as the task's implementer. --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 identifies the current approval items. Repeating the same pending assignment returns those same identifiers without creating another request. A different assignment target is rejected until the current request is approved or rejected.

Pull-request commands record reports only. Source operations still happen through the repository's own CLI, SSH, or another source tool. After each push, report both --ci-status and --merge-status from the source. Pending or unavailable checks keep the task blocked through tama tasks recheck. Failed checks or conflicts return it to implementation. A changed --head-sha, newly failing required check, or newly reported conflict clears the earlier readiness and Task Machine decision. Task Machine approval never substitutes for required source-host approval, and source-host approval never substitutes for Task Machine review. After merge-check returns allowed: true, merge through the source tool and immediately report --state merged for the same commit.

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 finds runnable workflow definitions and starts the selected definition under one task when the work should move through a repeatable process instead of a one-off follow-up.

Command	What it does
tama workflows list	List visible runnable workflows, optionally filtered by --query.
tama workflows search <query>	Search visible runnable workflows for the given text.
tama workflows start <workflow-id> --task <task-id>	Start one existing workflow definition for one task, reading an optional JSON object from standard input. The JSON result reports whether the run started immediately or is waiting for approval.

list and search accept --limit and return compact identity, name, description, project, publication, and status fields. Only active definitions are returned. Draft, archived, proposed, and reusable playbook definitions are excluded because they are not workflow start targets.

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

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 projects

tama projects reads active projects visible to the agent so it can select a real project id before linking or proposing work.

Command	What it does
tama projects list	List visible active projects, optionally filtered by --query.
tama projects search <query>	Search visible active projects for the given text.
tama projects show <project-id>	Show one visible active project. Missing, proposed, archived, and out-of-workspace ids are not returned.

list and search accept --limit. Project responses include the stable id, name, prefix, description, and status needed to select a target.

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

Command	What it does
tama secret list	List vault credentials with metadata only — name, kind, website, username, and whether an authenticator is set. Never returns a password, secret, or seed.
tama secret search <query>	Search that same metadata by name, username, website, or kind.
tama secret request --domain <d> --kind <k> --reason <why>	Ask for a missing credential after search finds no suitable entry. Add --can-sign-up when a separate account can be created. Returns request metadata only.
tama secret get --field <f> @<ref>	Resolve one field (username, password, secret, or totp) and print only its raw value to stdout for shell command substitution.
tama secret exec [refs] -- <command>	Resolve credential references and run <command> with the values injected into the child only.
tama secret generate --name <n> --url <u>	Have the server mint a strong password and seal it into a new credential; prints only metadata. Accepts --kind and --username.
tama secret set --kind <k> --name <n> --url <u>	Create a credential (a login, api_key, or generic secret). Takes --username, and either --password or --generate, plus an optional --totp-seed. Audited and raises a workspace notification.

Use request only after search confirms the workspace does not already hold a suitable credential. The request includes the website, credential kind, and the reason the current work needs it. It creates one deduplicated Inbox decision and returns no password or secret. After a request succeeds, the agent ends its turn and waits for a human to select or add a credential, approve a separate account signup, or reject the request.

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. During a run those flags cannot switch the command into another agent or workspace.

tama documents

tama documents reads and writes Library 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 document titles, paths, and bodies by fused lexical and semantic relevance.
tama documents show <document-id>	Show one document.
tama documents create --title <title>	Create a document, reading its body from standard input.
tama documents update <document-id>	Append a document version, reading its body from standard input.

create requires --title. It accepts --content-path for a destination folder, defaulting to the workspace Library, plus --content-type, --checksum, and --task for source attribution. update accepts --content-type and --checksum. File storage references and the current agent-run source come from supported upload paths rather than being copied from another run.

tama memory

tama memory inspects and edits one agent's memory. It is 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 positional agent id selects the memory owner. During a run, the agent and workspace must stay within that run's authorized scope.

tama agents

tama agents finds visible agent targets and carries commands an agent runs about its own improvement.

Command	What it does
tama agents list	List visible agents, optionally filtered by --query.
tama agents search <query>	Search visible agents for the given text.
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). --task optionally attaches the question to a task for context.

list and search accept --limit. Their compact results include the agent membership id used as a command target, the profile id, display name when available, summary, status, and autonomy level. They never return profile instructions, memory, reasoning, or model settings.

tama teams

tama teams finds visible team targets and lets a lead agent route its team's queue.

Command	What it does
tama teams list	List visible active teams, optionally filtered by --query.
tama teams search <query>	Search visible active teams for the given text.
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 one team member as its implementer.
tama teams route-thread <team-id> <comment-id> --assignee <id>	Route a team comment thread to an agent teammate.

list and search accept --limit and return compact team ids, names, descriptions, statuses, and lead membership ids. Team discovery follows workspace membership visibility. Queue and routing commands still require the acting agent to lead the selected team.

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.

Command	What it does
tama playbooks list	List playbooks visible to the agent.
tama playbooks search <query>	Search bundles by job text, category, and contents.
tama playbooks generate <description>	Ask the managed model to design a custom playbook and immediately raise one install proposal for approval.

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

generate is the model-backed path for a job the catalog does not already cover. It requires --rationale and --project, accepts an optional --goal, and returns the pending playbook_installation plus a compact summary of the proposed design so the agent can describe it without pasting bundle JSON.

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. Task Machine supplies the current workspace, agent, and chat during a run. Explicit flags cannot escape that authorized scope. --chat may select another chat only when it belongs to the same agent in the same workspace, and only the chat's own agent may rename it.

tama propose

tama propose creates, inspects, and withdraws agent-authored proposals. Task Machine supplies the proposing agent during a run, so proposal commands do not expose --agent. --workspace selects the workspace without allowing a run to escape its authorized scope. Creation requires --rationale. A pending proposal does not apply its change. It routes a self-contained approval item to the people who can decide it.

The JSON-on-stdin proposal kinds are workspace, team, agent, skill, mcp, task, project, goal, and workflow. A workspace proposal needs only name in its JSON body:

tama propose workspace \
  --rationale 'Separate regional policy and delivery work' <<'JSON'
{
  "name": "European Operations"
}
JSON

Approving that proposal creates a separate sibling workspace owned by the human who approves it. Task Machine does not copy the source agent, other members, or records into the new workspace. Rejecting or retracting it creates no workspace.

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 launch shape through the official Model Context Protocol registry and never accepts credentials on this path. Propose required setup before attempting dependent work, and continue only after approval, account authorization, and agent assignment.

Use tama propose mcp only for a custom server outside the catalog. Describe its non-secret shape with fields such as name, server_type, command, and args. A skill proposal carries reusable instructions and does not replace missing service authorization.

Task and project proposal payloads can include goal_id when the agent leads that goal. Approval activates the task under the goal or adds the project assignment. Nothing appears in the goal before the decision.

tama propose playbook --from <workflow> promotes a proven workflow into a reusable workspace playbook. tama propose bundle <bundle-slug> proposes a catalog playbook install, with optional project_id and config JSON on standard input. tama propose generated-playbook sends a complete generated bundle JSON. Bundle and generated-playbook approval installs the unit transactionally. Rejection or retraction creates no work-graph records.

tama propose chat

tama propose chat proposes starting a child chat from the current chat. It requires --target-agent, --title, and --rationale, and reads the opening prompt as plain text from standard input.

printf '%s' 'Review the disputed charges and summarize the evidence.' | \
  tama propose chat \
  --target-agent 9b1d2f70-53f4-4e27-9eb8-cf625f645912 \
  --title 'Billing evidence review' \
  --rationale 'The finance specialist should verify the disputed charges'

During a run, Task Machine supplies the source chat and source work record. Outside that context, pass matching current-turn records with --source-chat and --source-worker-run. The server verifies the source workspace, chat, run, proposer, and active target agent. Approval-gated opening prompts remain deferred until a source-chat manager approves them.

tama propose list and show

tama propose list returns pending proposals raised by the current agent in the current workspace. --kind <kind> filters by a creation kind or alias. --state proposed|active|rejected|all selects lifecycle state. Use all to inspect decision history.

tama propose list
tama propose list --kind connector --state rejected
tama propose show workspace 7df4b99c-504a-4746-915d-1ff11b15211c

tama propose show <kind> <proposal-id> returns one current-agent proposal, including approved or rejected history. Other agents' and other workspaces' proposals are not disclosed.

tama propose retract

tama propose retract <kind> <proposal-id> withdraws one still-pending proposal raised by the current agent. It accepts every creation kind and alias: workspace, team, agent, skill, MCP/connector, task, project, goal, workflow/promoted playbook, chat, catalog bundle, and generated playbook.

tama propose retract task 7df4b99c-504a-4746-915d-1ff11b15211c

Retraction rejects the durable proposal, records that the proposing agent withdrew it, and completes its approval Inbox items. It cannot withdraw an approved or already rejected proposal. --workspace cannot escape a run's authorized scope, and there is no --agent flag. Success prints:

{
  "ok": true,
  "kind": "task",
  "id": "7df4b99c-504a-4746-915d-1ff11b15211c"
}

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 Task Machine starts, see getting started.