CLI commands

The tama CLI operates optional Local Workers and lets agents read and update workspace records during Cloud or Local Runs. It groups operator commands and agent resource commands. A person uses setup, version, status, sync, update, workers, daemon, and the startup helpers to operate a machine.

An agent's worker uses the resource commands 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 CLI setup.

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. Accepting installs the startup entry. Setup 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 workspaces

tama workspaces list returns one bounded page of the workspaces selected during setup that remain active and accessible to the signed-in person. Each result contains only the workspace ID and name. Workspaces joined after setup are not added automatically; run tama setup to change this machine's selection.

Use --limit to request between 1 and 100 records (25 by default). Continue a multi-page result with --after <next_cursor>. A cursor is valid only for the same connection and workspace selection.

tama status

tama status prints a health report with three parts:

• Local process: app URL, installed CLI version, running state, active Runs, target capacity, and room for new starts.
• Capacity decision: the admission reason, processor and memory sample, automatic or temporary target, pressure, and conservative fallback when monitoring is unavailable or stale.
• Connection: server reachability, then each Workspace's machine ID, reported daemon version, status, last heartbeat, execution root, and coding tools.

When the installed binary is newer than the running daemon, the daemon-version line says that a restart is required. Local state prints even when the server is unreachable or credentials have expired. Those problems appear as a labeled server line with the tama setup command to reconnect.

If the saved connection needs renewal, the CLI handles that automatically first. Use status after setup, when work is waiting, or when a machine looks offline.

tama sync

tama sync asks Task Machine already running on the computer to detect its coding tools and refresh every connected workspace immediately. It fails with a start command when Task Machine is not running.

When the running daemon is older than the installed CLI or predates the local sync protocol, tama sync safely requests a restart instead. The replacement waits for active work to finish and syncs immediately after it starts.

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. When the daemon is running, it finishes active work and restarts from the installed binary before its next full sync.

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 without contacting Task Machine, so it is the fastest way to confirm a tool is on PATH before connecting.

tama executables

tama executables manages Task Machine's signed coding and browser dependencies. They are installed automatically when an authorized run first needs them, so this command is mainly useful for preparing a machine before it goes offline or inspecting and repairing its local cache.

Command	What it does
tama executables install <code|browser|all>	Download and verify the current dependency bundle, or reuse the verified local copy.
tama executables status <code|browser|all>	Report whether each current bundle is ready on this machine.
tama executables prune <code|browser|all>	Remove superseded versions while retaining the version used by this tama release.

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 restart	Ask Task Machine to finish active work, restart on any supported operating system, and sync immediately.
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.
tama daemon concurrency set <runs> --for <duration>	Temporarily replace the automatic local Run target with a whole number from 1 through 20. The daemon must be running.
tama daemon concurrency reset	Remove the temporary target and return to automatic capacity, whether or not the daemon is currently running.

A concurrency target expires at the absolute time printed by the command, including across an automatic daemon restart. It changes the target only: current memory headroom and processor-pressure braking can still admit fewer new Runs, active work is never interrupted, and workspace limits remain authoritative.

Use tama status to see the effective target and the reason another Run can or cannot start. 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 the command as its first argument, 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	Commands that return bounded pages	Maximum results for the current page.
--after	Commands that return bounded pages	Continue from one page cursor returned by the previous page.

tama tasks

tama tasks reads and updates tasks as an agent. Every <task-id> argument accepts either the task's canonical readable key, such as OPS-42, or its UUID. Current and historical readable keys resolve to the same task. The <blocking-task-id> argument for dependency creation follows the same contract.

Successful responses and saved relationships continue to use the canonical task UUID.

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 with fused lexical and embedding relevance. The page envelope reports whether semantic ranking was available.
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, duplicate_relationships, 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 time <task-id>	Show the task's active agent seconds, elapsed wall-clock seconds, and sparse active seconds by execution stage, plus a bounded agents page. Each Agent entry contains only agent_membership_id, active_seconds, and sparse stage_active_seconds. Use --limit and continue with --after <next_cursor> while has_more is true. Each request is a fresh aggregate, so restart from the first page if qualifying work may finish during traversal. Tasks without usable timing return null totals, empty stage and Agent collections, no cursor, and has_more: false. These operational durations are not chargeable billing duration.
tama tasks usage <task-id>	Show the task's all-time spend in the workspace currency, including exact decimal amounts grouped by execution stage. Tasks without recorded usage return zero spend and an empty stage map.
tama tasks labels list <task-id>	Return one bounded page of labels assigned to the task, including archived historical assignments. Accepts --limit and --after.
tama tasks labels add <task-id> <label-id>	Add one active label from the task's Project without replacing its other labels. Exact retries return changed: false.
tama tasks labels remove <task-id> <label-id>	Remove one active label from the task without replacing its other labels. Exact retries return changed: false.
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, repository_selection, 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. Once work is queued with a Team, use tama teams route and choose an active Team member returned by tama teams queue as its implementer. The JSON result reports whether the change 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). Optional knowledge_refs lists the current run's knowledge references the agent claims to have relied on.
tama tasks summary <task-id>	Replace the task's rolling summary from standard input. The command checks the trimmed body locally before making a request, counts Unicode grapheme clusters, and rejects more than 4,000 with an error that reports the actual count, 4,000-character maximum, and exact excess. Valid input is forwarded unchanged. The body accepts at most 15 top-level - bullets and otherwise uses plain paragraphs with inline links, bold, italic, or code. Headings and other block formatting are not supported.
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. Optional --knowledge-refs <file> reads claimed knowledge references from a separate JSON array file.
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> [--merged-at <RFC3339>] [review context flags]	Report the source state and current commit. A different commit deactivates the current review while preserving approval evidence for its exact approved commit. A later report can reactivate that evidence only for the same pull request and commit when the source is open, CI is passing, mergeable, and source-host approved when required. If an assigned agent reviewer approved and passed merge-check but the source merge does not complete, that reviewer may report the unchanged approved commit as open with its current CI and mergeability values, including a still-passing and mergeable state. A same-head report that remains passing, mergeable, and source-approved when required preserves approval; failing, conflicting, or otherwise unready evidence clears it for recovery. Never report it as merged unless the source confirms it. Repeat the review-context flags after each push. Use --merged-at only with --state merged to report the provider's actual RFC3339 merge time. Offsets are normalized to UTC. Use --source-review-required and --source-review-state when repository rules require separate source-host approval. If the URL is linked to readable same-workspace Tasks but not the supplied Task, the rejected report lists up to 20 current Task keys and says when more exist so you can retry against one. Hidden or unavailable ownership keeps the generic error.
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, the source reports it mergeable, and any source-host approval required by repository rules has been reported.
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. A final agent approval continues immediately through merge and completion. Pre-review stops after its verdict. Human final reviewers use the Inbox instead. Optional --knowledge-refs <file> attaches claimed knowledge references to that exact decision.
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. Use this from an assignment or comment-triggered Run instead of tama tasks waiting. 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 normal or urgent automatic backoff until the recheck is cleared or the task leaves Blocked. A recheck records waiting when the condition is unchanged or needs_implementer when concrete work exists. Missing outcomes use bounded recovery, and only a typed human request creates Inbox attention.
tama tasks request-repository-access <task-id>	Ask a human to choose or create repository context when the current task Run discovers that source is required. The command uses the current Run identity, blocks the task, and creates or reuses one Repository needed Inbox decision. Repository-free tasks remain valid until this explicit request.
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 contain exactly one active human mention in the form @[name](member:<id>).
tama tasks waiting <task-id>	Record that an automatic recheck Run confirmed its durable waiting condition, with the reason from standard input. The trimmed reason may be at most 500 characters. Shorten longer reasons and retry. This outcome is not available to assignment or comment-triggered Runs. Use tama tasks recheck for an ordinary external wait.
tama tasks needs-implementer <task-id>	Route concrete work found by an automatic detector to the task implementer, with the next step from standard input. The trimmed reason may be at most 500 characters. Shorten longer reasons and retry. This outcome is also reserved for automatic recheck Runs.
tama tasks needs-help <task-id> --assignee <member-id> --attempted <work> --blocker <condition> --recommendation <next-step>	Create a self-contained human question from standard input and record the Run's human dependency.
tama tasks question <task-id> --assignee <id> [--parent-comment <comment-id>] [--option <answer>]...	Ask a human a question on the task. The assignee is required. On an active, unarchived Done Task, this atomically reopens the Task to in_progress before creating, repairing, or reusing the handoff. Cancelled Tasks remain closed and reject the question. Use the existing thread root as --parent-comment for a clarification or follow-up. Omit it only for a distinct topic. Repeat --option up to five times to offer predefined answers in their displayed order.
tama tasks withdraw-question <task-id> <question-id> --basis <basis>	Withdraw the agent's exact unresolved question returned by tama tasks show when durable information makes the answer unnecessary. Visibility through tama tasks show does not grant withdrawal ownership: compare asked_by_membership_id with the active agent, and if another agent asked it, leave the question open for the assigned human or asking agent instead of retrying. The question may be older than the Task's current pending pointer, but must belong to the same Task and originate from the same agent. For an assigned human's unambiguous 👍, reload the task and use superseded_by_human_direction only when the reaction is on the exact current unanswered and unwithdrawn typed question and the reacting member matches its assignee. The reaction remains human direction, not a text answer. Pipe a nonblank reason of at most 500 characters through standard input. Other bases are new_information and resolved_independently. The authenticated active Worker Run must belong to the same task and agent. Stale, ambiguous, other-member, and other-emoji cases remain open for an explicit answer. Withdrawal system-skips only that question's Inbox attention. A non-pointer withdrawal leaves the current pointer and newer question unchanged. It cannot bypass approval, review, safety, authorization, or unresolved judgment.
tama tasks approval <task-id> --assignee <id> --deduplication-key <key> [--subject-reference <type>:<id>]... (--standalone | --context-comment <comment-id> [--attach <path>]... | --attach <path>...)	Request a Human decision from standard input with a stable deduplication key and one explicit standalone or contextual evidence mode, as explained below. The owning Task is always included.
tama tasks withdraw-approval <task-id> <approval-request-id> --basis <basis>	Withdraw the agent's exact pending approval when durable information makes the human decision unnecessary. Pipe a nonblank reason of at most 500 characters through standard input. The basis is new_information, resolved_independently, or superseded_by_human_direction; only the requesting agent's active Worker Run for the task may use it.
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 duplicates mark <task-id> <duplicate-of-task-id>	Add one duplicate relationship. Active work is cancelled atomically, while completed or cancelled work keeps its terminal state. Other duplicate relationships remain unchanged and exact pair retries return changed: false.
tama tasks duplicates remove <task-id> <duplicate-of-task-id>	Remove one exact duplicate relationship without reopening the Task or changing its other relationships. Exact retries return changed: false.
tama tasks dependencies add <task-id> <blocking-task-id>	Add a blocking-task dependency. Attaching a pending proposed repair clears the dependent task's automatic recheck and waits for the proposal decision.
tama tasks dependencies remove <task-id> <dependency-id>	Remove a task dependency.

For a tama propose task JSON object, choose the appropriate repository_selection:

Value	Effect
project_default	The default. Resolves the Project's configured repository and stores that source identity, which may be null.
repository	Uses a non-empty git_repository_id from the same Workspace.
not_required	Stores no repository. Use a null git_repository_id when the work needs neither repository context nor a repository deliverable.

{
  "project_id": "PROJECT_UUID",
  "title": "Review the Operations queue",
  "repository_selection": "not_required",
  "git_repository_id": null
}

progress is for a current action that needs one human, not a routine status update. Its standard-input body must contain exactly one active human member reference in the canonical @[name](member:<id>) form, where <id> is the workspace membership id. A bare @name, an agent: reference, or a team: reference does not satisfy the human-owner requirement.

For example, replace <human-membership-id> with the id returned by tama tasks show:

printf '%s\n' 'Please choose the launch window @[Human owner](member:<human-membership-id>)' | \
  tama tasks progress TAS-42

list and search both accept --limit and --after <cursor>. They return a JSON page envelope with this shape:

{
  "tasks": [],
  "next_cursor": null,
  "has_more": false
}

Search normalizes case and punctuation into bounded terms, then matches those terms across the task title, description, summary, Work Spec, acceptance criteria, status, proposal rationale, project, and readable task key. Short searches require every term. Longer searches allow limited extra context while rejecting weak one-word overlap.

Fresh task changes are searchable immediately without waiting for background semantic indexing. 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 normalized query context, so if you change its terms you start again from the first page instead of reusing an older cursor.

An open Work Spec keeps agent status changes gated until approval, except an explicit reasoned move to blocked, and the approval request itself never changes status.

time distinguishes successful work sessions from elapsed time. Only succeeded Runs contribute, and automatic blocked or pull-request rechecks never count regardless of their result.

Overlapping included Runs each add their own active seconds, while elapsed seconds span from the first included session starting to the last included session ending and therefore retain pauses between those sessions. Failed, cancelled, timed-out, and unfinished Runs remain visible in Run history without inflating these totals.

usage reports customer-facing task spend rather than a budget's current-period consumption. Both responses use sparse stage maps, so an absent stage means zero. Neither command estimates values from task lifecycle timestamps or budget limits.

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. A repository update supplies both repository_selection and git_repository_id: use repository with a nonblank id, or use project_default or not_required with a null id.

pull_request_required is visible in Task responses as the current Project setting and cannot be changed through agent update. 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 and represents the complete desired set. Prefer the dedicated tasks labels add and remove commands for one-label changes so concurrent work never replaces a stale full-set snapshot. Both paths accept only active labels from an active task Project.

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.

tama tasks comment --attach and tama tasks approval --attach use the shared Comments and attachments contract. Unsupported files are rejected before any Task, comment, attachment, approval, Inbox, timeline, audit, or realtime state is created. For patch evidence, save textual patch or diff evidence as a .txt file before retrying. Do not disguise incompatible binary content with a false extension.

approval uses --deduplication-key as the durable identity of one decision, independent of the request wording. The key must match ^[a-z0-9][a-z0-9:_-]{0,199}$: one to 200 ASCII characters, starting with a lowercase letter or digit and continuing with lowercase letters, digits, colons, underscores, or hyphens. visual-verification is a valid hyphenated example. Choose standalone mode or contextual evidence. Do not combine --standalone with either contextual flag.

withdraw-approval cancels only the exact pending approval identified by <approval-request-id>. The active Run must belong to the same workspace, task, and requesting agent that created the approval; a newer Run for that agent is valid. Withdrawal preserves the approval in approval_requests history, records the basis, reason, membership, Run, and time, and system-skips the recipient's active Inbox attention. It never approves, rejects, resumes work, or creates a human decision. Missing, foreign, decided, superseded, and already withdrawn requests return approval request not found.

Choose the context mode that matches the evidence:

• --standalone: the request body contains everything needed to decide.
• --context-comment: bind an existing Task conversation.
• --attach: attach up to ten new screenshots, recordings, or files. Repeat the flag for each file.
• --context-comment with --attach: add new evidence to an explicitly selected conversation. Task Machine creates the evidence comment inside that thread and binds it to the approval.

Task Machine creates and binds attachment context automatically. Do not describe evidence as attached to a standalone request.

A repeated request with the same key and context reuses the pending approval. Changed wording, scope, capability, subject, or attached evidence 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. A clarification or follow-up stays in its existing conversation by passing that thread's root comment id with --parent-comment. A genuinely distinct topic omits the flag and starts a new thread. Each repeated --option adds one short predefined answer, and Task Machine shows those answers in the order supplied.

On an active, unarchived Done Task, asking a question atomically reopens the Task to in_progress before creating, repairing, or reusing the human handoff. The normal Task lifecycle action clears completion timing, preserves the established start time, and records status evidence, analytics, queue, retention, and realtime effects. A Cancelled Task remains closed and rejects the question without side effects. Do not update status separately or retry around that barrier.

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 or the requested direct member was already the Task's implementer. An exact same-member retry returns the unchanged Task, timeline_event_id: null, and inbox_item_ids: [].

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

When reconciling a source-confirmed merged pull request, pass the provider's actual merge time with --state merged --merged-at <RFC3339> when it is available. The timestamp is normalized to UTC; malformed timestamps and use with open or closed state fail locally before the request is sent. Pass explicit source-review fields when the source provides them: a changed merged head preserves that reported source evidence, but Task Machine review_state remains pending and no Task Machine approval or merge authorization is inferred. Omitting --merged-at preserves the existing server-clock fallback for a first merged report and the stored time on later retries.

A changed --head-sha, newly failing required check, or newly reported conflict deactivates the earlier readiness and current Task Machine approval. Task Machine preserves that approval only for its exact approved commit.

A later report for the same canonical URL can reactivate it when the source says open, CI is passing, the head is mergeable, and any required source-host review is approved. No new review command or Inbox item is created. Any other commit needs its own review.

Any pending approval whose structured subject explicitly references that pull request is also superseded and its Inbox item is skipped without inferring a decision or creating a replacement request. Task-only approvals, approvals for another pull request, and prior human decisions remain unchanged.

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. If that source merge does not complete, report the same approved commit as open with its current CI and mergeability values, including a still-passing and mergeable state, instead of claiming a merge. A same-head report that remains passing, mergeable, and source-approved when required preserves approval; failing, conflicting, or otherwise unready evidence clears it for recovery.

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 definitions	Inspect draft and active definitions with server-side --query, --limit, and --after pagination. Drafts are not runnable.
tama workflows show <workflow-definition-id>	Inspect a definition and its graph with --section nodes, edges, or conditions. Continue each section with --after until has_more is false.
tama workflows schedules	Inspect Workflow-linked schedules without activating them.
tama workflows schedules list	Search schedule briefs or exact schedule/definition IDs with --query. Use --limit and --after to continue pages.
tama workflows schedules show <schedule-id>	Read exact cadence, timezone, Connector readiness and activation. Unset fields stay null.
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.
tama workflows http --method <method> --path <relative-path>	During an http_request node, make one server-composed call to the configured HTTPS origin. Repeat --query or --header, and use --body, --body @file, or --body - as needed. Credentials are injected and redacted server-side.

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 with its server-issued Playbook reuse ID and fingerprint.

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 with its server-issued Playbook reuse ID and fingerprint. 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 repositories

tama repositories discovers active reusable Git repository metadata without returning credentials or SSH key material.

Command	What it does
tama repositories list	List visible repositories, optionally filtered with --query and bounded by --limit.
tama repositories search <query>	Search by repository name, clone URL, or default branch.
tama repositories show <repository-id>	Show safe clone metadata for one active workspace repository.

Use the returned stable id in Project, Task, Workflow, schedule, and generated-Playbook repository fields. When the required public or private repository is not connected, use tama propose repository rather than guessing an id or putting credentials in a proposal.

tama workers

Bare tama workers detects local provider tools for human setup. During an agent Run, tama workers list and tama workers show <worker-id> return agent-enabled workspace Workers with their Machine names, providers, models, and reasoning levels. They omit executable paths and credentials. A fixed Agent configuration copies the exact model, reasoning, and default_worker_id from this output.

tama labels

tama labels discovers active native Task Machine labels before an agent classifies a task. These commands never create a label and never return proposed, rejected, or archived definitions.

Command	What it does
tama labels list --project <project-id>	Return one bounded page of active labels in the Project.
tama labels search <query> --project <project-id>	Search active label names, descriptions, and colors in that Project before pagination.
tama labels show <label-id>	Show one active label visible in the workspace.

List and search require --project, default to 20 results, cap one page at 100, and accept --after <cursor>. The page envelope contains labels, next_cursor, and has_more. A label response carries its stable id, Project id, name, description, color, position, and lifecycle timestamps. Use tama propose label --rationale <why> when no existing label fits.

There is deliberately no tama labels create command.

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, referencing credentials by @<name-or-id>. Secret discovery returns metadata only. Prefer tama secret exec to inject resolved credentials into a child process and redact matching values from its output.

tama secret get deliberately returns plaintext to stdout, so callers must prevent it from entering terminal output, logs, prompts, or transcripts.

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 --service-name <name> for the tool or app, --url <url> for the exact HTTP(S) target, and --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. A login may omit --password/--generate for email or magic-link sign-in, while other kinds require one. An optional --totp-seed configures login two-factor authentication. 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 private 0600 file, preferring a runtime directory or tmpfs and warning if it falls back to the OS temporary directory where plaintext may touch disk. Its path is exported as TAMA_SECRET_<NAME>_FILE with the name upper-cased.

Passing --as-env NAME delivers the value in a plain environment variable NAME instead. Exact matching values are redacted from the child's stdout and stderr, but transformed values are not covered by that redaction. If credential resolution fails or access is pending, the child does not run and the command exits non-zero.

get resolves one field and prints its raw value to stdout for callers that must pass it through a controlled shell. On missing access, it returns no value and exits non-zero. The caller must check that status before running a dependent command.

Embedding $(tama secret get ...) inside another command does not stop that outer command when resolution fails. Prefer secret exec, which does not launch the child when resolution fails.

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 context

tama context inspects the saved knowledge recorded for the current agent run. Knowledge references distinguish memory supplied in the prompt, content opened during the run, and Skill preparation reports. Receiving content or reporting a prepared Skill does not prove that it was useful.

Command	What it does
tama context list [--after <cursor>] [--citation-set <id>]	Return one page of up to 25 reference summaries without source bodies. Continue with next_cursor while has_more is true. Use --citation-set to inspect the references attached to an accessible plan or review.
tama context show <reference-id>	Read the exact saved version under current permissions and return a reference for the current run. Missing or unavailable historical content fails rather than opening today's version.

tama tasks show includes current_plan_knowledge_citation_set_id for a reported declaration on its exact current_plan_revision_id. Each reported Task-review declaration has knowledge_citation_set_id beside that review's ID and kind. An absent field means unreported, not that no knowledge was used. An explicitly empty declaration still has a set ID.

Successful plan and review submissions return knowledge_citation_set_id as their receipt. That receipt belongs to the submitted decision. It must not be treated as a lookup of the latest plan or pull-request review.

Only references marked claimable can be submitted for the current run. Opening another run's accessible reference creates the current run's own record. Library search results and paths alone do not count as opening content, and a Skill download or repository override does not count as a prepared Skill.

For a plan, put the claimed reference IDs in the spec JSON's knowledge_refs array. For a Task or pull-request review, pass a JSON array file with --knowledge-refs. Keep the explanation in the plan's Context reviewed section or existing review notes. An omitted declaration means the agent did not report its references, while an explicit empty array means it claims none. The CLI submits larger lists in bounded batches before recording the decision.

Older runs may report capture_status: "not_captured". That state does not establish that no knowledge was supplied. References add no permissions, approval or verification bypass.

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 with its server-issued Playbook reuse ID and fingerprint.
tama documents create --title <title> [--task <task-reference>]	Create a document, reading its body from standard input.
tama documents update <document-id>	Append a version to a generated document, 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. --task accepts a Task UUID, current readable key such as OPS-42, or a retained readable key from before a Project move. The server resolves the reference within the current workspace and agent permissions, then stores the canonical Task UUID in provenance. update accepts --content-type and --checksum. Direct agent updates are limited to generated documents and still require the relevant path permissions. Human-authored documents remain read-only through this command.

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>	Submit a deduped memory consolidation in the background and print its pending operation. The resulting candidate remains for a human to accept or discard.
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, changes their display names through the configured update gate, 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 show <agent-membership-id>	Read accepted Agent configuration, its server-issued Playbook reuse ID and fingerprint, and Connector assignment IDs with Agent and Connector read access. Use --limit and --after to continue assignments. No credentials are returned.
tama agents rename <agent-membership-id> <new-name>	Rename one existing active agent. --rationale is required.
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.
tama agents question list	List the current agent's recent questions across all statuses, newest first. Use --status open|answered|cancelled|all and --limit 1-100 to narrow the bounded result.
tama agents question show <question-id>	Show one question with its exact persisted answer, status, and resolution timestamps.
tama agents question propose <question-id>	Submit one complete replacement instruction body from standard input for an answered instructions question. The replacement goes through human review.

Agent discovery 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. Use that stable membership id with rename.

Its result reports pending when approval is required and applied when the configured agent-update gate permits the new display name directly. Renaming keeps the existing agent identity and settings.

After a human responds to a self-improvement question, inspect the answered question before relying on its answer. For an instructions answer, translate the feedback into durable guidance, preserve every current instruction that still applies, and submit the complete replacement rather than copying the answer directly.

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 show <team-id>	Inspect the current roster's member IDs and Team roles without member-directory access. Use --limit and --after until has_more is false. The result includes the server-issued reuse ID and fingerprint for Playbook proposals.
tama teams queue <team-id> [--after <cursor>]	Read the next bounded, resumable backlog page for the lead agent's Team, including member load and continuation state. The lead's workspace role must include task:read; Team leadership does not grant it.
tama teams route <team-id> <task-id>	Read a complete JSON recommendation from stdin and atomically route, defer, block, cancel, or mark the Task as a duplicate. The command requires task:read. A route uses task_changes.assignee_membership_id for an active Team member returned by tama teams queue. It may use task_changes.planner_membership_id and task_changes.reviewer_membership_id for separate eligible active workspace members. Duplicate decisions require one to ten duplicate_of_task_ids. Approval-gated recommendations return a distinct Team routing review.
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 and show use Team read access. Queue and routing commands require the acting agent to lead the selected team and have Task read access through its current workspace role.

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>	Submit a custom playbook design for background generation and return its operation id immediately.
tama playbooks generation <operation-id>	Inspect the current status and identifier-only result of one submitted generation operation.

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. The description and --rationale are required. --goal optionally links an existing Goal. Write the description as a self-contained execution brief with the complete setup, reuse rules, execution choices, inputs, deliverables, timing, approval boundaries, and prohibited actions. The generator receives the description and compact context for every reusable Playbook resource, repository, and eligible Worker. It does not inherit Chat history, repository access, earlier file reads, tool results, or the rationale. Read referenced source material first and include its relevant requirements instead of submitting only a file path. A path, URL, filename, or Chat reference alone is rejected because the managed generator cannot read it; supply the readable contents or ask the person for them. Use the rationale to explain why the setup fits.

The generator declares exactly one Project to create or explicitly reuse. generate accepts the one positional description shown above rather than a file, stdin, repository-reading, or additional-flag input mode.

The command returns a durable generation operation immediately. The originating Chat receives the outcome automatically when generation finishes. tama playbooks generation <operation-id> is an optional status lookup. Successful operations identify the pending Playbook installation so the agent can inspect its immutable manifest before describing the design in prose.

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.
tama chats request-repository-access	Ask an authorized person to choose repository context for the current Chat.
tama chats response-options [--option <response>]...	Offer up to five editable suggested responses with the current answer.

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, Chat, and Run during a turn. 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.

When a conversation needs source context and the Chat has no repository, run tama chats request-repository-access. The command uses the authenticated current Chat and Run by default. It creates one Inbox decision for the active Chat owner when they can manage the Chat and workspace repositories.

The owner can choose an active workspace repository, create one, or decline. The agent must not guess or clone a repository URL from the conversation. After the decision, Task Machine resumes the Chat and keeps an approved repository as its working context for later turns.

response-options is more narrowly bound to the active Chat turn and cannot target another Chat. Each repeated --option adds one ordered response of at most 120 characters. Options must be unique and nonblank, and repeating the command replaces the current set. Running it without any --option clears the set.

The suggestions appear only with that turn's latest agent answer. Selecting one fills the ordinary composer for editing and never submits it automatically, so a person can change it or write a different reply before sending.

tama propose

Before proposing work, choose the smallest durable structure:

• Task: one-off work.
• Workflow or recurring Task: repeated work.
• Agent instructions: standing responsibility for an existing Agent.
• Playbook: a coordinated recurring operation.

Do not use a one-off setup Task as the only representation of recurring behavior.

Every submission requires the entity's proposal permission, whether it creates a resource, revises one, or changes a relationship. The default Agent role includes these permissions.

Management permission alone does not authorize proposal submission, and proposal permission does not grant human review authority.

For standing guidance, agents can propose an append-only instruction addition for another active agent. The target's private instructions are loaded server-side, the response contains only a pending proposal identity, and a human must approve the exact diff in the Inbox:

printf '%s\n' 'Keep all Linear mirror updates hourly.' | \
  tama propose agent-instructions --target-agent <membership-id> \
  --rationale 'The role needs a durable recurring responsibility'

This command cannot target the proposing agent or replace or remove unknown instructions. Use tama agents question --target instructions for self-improvement.

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, label, project, repository, 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 agent-update <agent-membership-id> revises an existing agent without creating another member. It accepts display_name, summary, instructions, model, reasoning, and skill_ids in its JSON patch. Omitted fields keep their accepted values. When skill_ids is present, it is the complete desired skill set, including every skill the agent should retain.

The result reports pending when approval is required and applied when the agent's separately configured update gate allows direct publication. For a display-name-only change, tama agents rename provides the shorter form without a JSON body.

tama propose agent-update 9b1d2f70-53f4-4e27-9eb8-cf625f645912 \
  --rationale 'Give difficult implementation a clear owner' <<'JSON'
{
  "display_name": "Senior Software Engineer",
  "reasoning": "medium"
}
JSON

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.

tama propose connector-assignment --rationale <why> assigns an accepted Connector to an accepted Agent through one immutable Agent-version proposal. Its strict stdin object contains agent and connector objects. Copy existing_agent_id and its nonempty existing_resource_fingerprint exactly from tama agents show. Copy existing_mcp_server_id and its nonempty fingerprint exactly from tama mcp list during the run.

Task Machine rechecks both references at creation and approval. Submitting this proposal requires agent:propose. Human approval separately requires Agent-management and Connector-assignment permissions.

The dedicated autonomy gate may publish directly. Otherwise, the Inbox shows the exact Agent, Connector, and rationale. Assignment requests required credential access but never grants it.

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.

tama propose repository --rationale <why> reads required name and clone_url plus optional default_branch from standard-input JSON. Approval creates reusable workspace metadata only. Never include credentials, tokens, SSH keys, or Vault ids. Provider-side access setup remains human-owned.

Task proposal payloads accept goal_id, repository and schedule fields, and exactly one optional implementer target: assignee_membership_id or assignee_team_id. They may also carry explicit planner_membership_id and reviewer_membership_id. Every selected member or Team must be active and in the workspace, and the proposing agent needs its effective assignment capability.

A required repair task may also set blocks_current_task: true. Task Machine creates the dependency from the authenticated source Run while bounded source rechecks continue inspecting independently changing source state. Assignment, planning, queue, notification, and execution effects remain dormant while a proposal is pending.

In the Inbox, a permitted human reviewer can replace or clear the implementer, planner, reviewer, project, goal, status, priority, repository, dates, schedule, recurrence, labels, title, and description in one approval decision. Approval activates the task with those final values and runs the ordinary effects once. Rejection or retraction wakes its waiting dependents.

Approval activates the task under the goal or adds the project assignment. Nothing appears in the goal or Team queue before the decision.

tama propose label --rationale <why> reads project_id, name, optional description, and optional lowercase #rrggbb color from standard-input JSON. It always enters the governed proposal path and never grants an agent direct label creation. The effective resource-creation gate resolves from the agent through the Project and workspace.

A gated result reports pending and creates a complete Project-manager Inbox decision. A permitted result reports applied. Use tama labels search first so a near-duplicate does not enter review.

tama propose label --rationale 'Billing needs one durable handoff signal' <<'JSON'
{
  "project_id": "2a628cee-188d-4ab6-a721-5319bf493a42",
  "name": "Ready for billing",
  "description": "Time entry is complete and ready to invoice"
}
JSON

A workflow proposal requires complete nodes, edges, and branch_conditions arrays so the execution graph is reviewable before approval. Node ref values are request-local and connect each edge or branch condition through its source and target. Applied proposals publish a runnable version immediately, while pending proposals publish that version when approved.

The built-in taskmachine-propose skill contains the exhaustive field, node-config, authorization, ordering, and topology contract.

Choose a Playbook proposal command for its source:

Command	Input and purpose
tama propose playbook --from <workflow>	Promote a proven Workflow into a reusable Workspace Playbook.
tama propose bundle <bundle-slug>	Propose a catalog install, with optional project_id and config JSON on standard input.
tama propose generated-playbook	Send a complete generated bundle JSON.

A generated Connector either names a canonical registry identity or reuses an accepted workspace Connector with existing_mcp_server_id. Task Machine hydrates and validates it before creating the proposal. A generated goal may carry an exact due_on date in YYYY-MM-DD form. 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 agent-update

tama propose agent-update <agent-membership-id> --rationale <why> proposes a focused update to an existing Agent using a JSON patch on stdin. The patch accepts display_name, summary, instructions, model, reasoning, and skill_ids. Omitted fields preserve accepted values. A supplied skill_ids list replaces the complete Skill set.

tama propose connector-assignment

tama propose connector-assignment --rationale <why> reads exact nested Agent and Connector reuse references from stdin. It adds only that accepted Connector relationship to the immutable candidate Agent version. Pending, approved, rejected, retracted, and stale history uses the connector-assignment lifecycle kind in list, search, show, and retract.

tama propose update

tama propose update <kind> <resource-id> --rationale <why> proposes a reviewed change to an existing Agent, Connector, Team, Project, Goal, Workflow, Workflow-linked schedule, or installed Playbook.

Individual resource commands take the accepted base_version_id plus the settings to change, with Workflow updates requiring a complete replacement graph. The command's --help output lists the complete schema for that resource.

For a Connector update, read current_version_id from tama mcp list inside the Run. Project and Goal list, search, and show commands also return current_version_id. Copy that value into base_version_id and use the resource's id as the update target. If the accepted version changes before you submit, read the resource again and review your changes against the new version.

A newer accepted version makes the proposal stale instead of overwriting the newer configuration.

Workflow and Workflow-linked schedule updates use workflow:propose. Human approval requires workflow:manage. If their update autonomy gate disables review, immediate publication also requires the proposing Agent's workflow:manage permission.

A Workflow update uses the stable workflow_id from tama workflows show as the positional <workflow-id>, not the inspected definition id. The inspected definition's id is both base_version_id and workflow.existing_resource_id, and its exact reuse fingerprint goes in workflow.existing_resource_fingerprint. Optional definition fields are top-level request fields, not members of the reuse reference. The request supplies complete replacement nodes, edges, and branch_conditions arrays.

Agent and Connector relationships use exact nested reuse references copied from tama agents show and tama mcp list. Raw relationship IDs are rejected.

Pending review leaves both the editable and runnable Workflow unchanged. Approval rechecks the base graph, permissions, and every reference before publishing the immutable candidate through the normal Workflow version path.

Schedule updates use the exact reference and current version returned by tama workflows schedules show. Supply only the description, approved timing and timezone, or inspected Workflow, Project, and Goal references that should change.

Pending review leaves the schedule unchanged. When switching between recurring and one-time work, explicitly clear the old timing. This command does not change direct Task schedules.

A Playbook update uses its installation id and a components array. Each component names an Agent, Connector, Team, Project, or Goal, its accepted base version, and its changes. Task Machine creates the typed candidates under one Playbook review, so the Inbox shows one decision with every current-to-proposed change.

Approval publishes the complete set or none of it. Rejection and retraction leave every current resource unchanged.

Update proposals use the lifecycle kinds agent-update, connector-assignment, connector-update, team-update, project-update, goal-update, workflow-update, schedule-update, and playbook-update in list, search, show, and retract.

tama propose list, search, and show

tama propose list returns one bounded page of proposals raised by the current agent in the current workspace. --kind <kind> filters by a creation or update kind or alias. --state proposed|active|rejected|all selects lifecycle state. Use all to inspect decision history. --limit defaults to 20 and is capped at 100.

When has_more is true, pass next_cursor to --after with the same kind and state.

tama propose search <query> searches pending proposal summaries raised by every agent in the current workspace. Use it before proposing to avoid repeating work that is already waiting for a decision. Search normalizes punctuation-separated terms and can match them across a proposal's title and rationale.

Task proposals also include their description, summary, Work Spec, and acceptance criteria, while label proposals include the proposed name and description. This means a query can combine a package name, check name, and implementation phrase without requiring that exact sentence in one field.

--kind <kind> narrows the proposal type, --limit bounds one page, and --after <next_cursor> continues until has_more is false. Search does not grant access to another agent's proposal detail or retraction actions.

tama propose list
tama propose list --kind connector --state rejected
tama propose search 'provider validation failure' --kind task
tama propose search 'weekly customer report' --after <next-cursor>
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. For generated-playbook, it also returns the exact immutable bundle manifest and SHA-256 identity used for human review, so a later turn can reload instructions, relationships, Connectors, schedules, and execution settings without reconstructing them.

Other agents' and other workspaces' proposal details 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, label, project, repository, goal, workflow/promoted playbook, chat, catalog bundle, generated playbook, and Connector assignment. It also accepts every *-update lifecycle kind.

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"
}

Additional visible command inventory

The command tree below completes the public surface. Run any listed command with --help for its arguments and flags. The focused skills explain the agent procedure and safety boundary where one applies.

Browser

tama browser operates the first-party browser attached to the current Run.

Use the browser commands for the action you need:

Action	Commands
Inspect or capture	tama browser status, tama browser snapshot, tama browser screenshot
Open or navigate	tama browser open, tama browser navigate, tama browser back, tama browser forward, tama browser reload
Point or activate	tama browser click, tama browser double-click, tama browser hover
Enter or select	tama browser fill, tama browser type, tama browser press, tama browser select, tama browser check, tama browser uncheck
Transfer files	tama browser upload, tama browser download
Wait or handle a dialog	tama browser wait, tama browser dialog
Complete a bounded objective	tama browser goal

Each command uses the tama browser prefix. Run tama browser --help for the full command list.

Page and environment controls are tama browser viewport, tama browser pdf, tama browser geolocation, tama browser offline, tama browser network, tama browser network-block, and tama browser storage-clear. Tab controls are tama browser tabs, tama browser tab, tama browser tab new, tama browser tab switch, and tama browser tab close. tama browser run inspects visual-history segmentation.

Start browser work with tama browser run new "<short goal>", using a trimmed name of 1 to 64 Unicode code points. The name identifies that visual-history segment without clearing tabs or browser state. The optional --name on tama browser goal names the Browser Run evidence, not the objective, and accepts at most 64 Unicode code points. If omitted, Task Machine derives the Browser Run name from the objective, capped at 64 Unicode code points.

tama browser upload <ref> <path> [path...] accepts a snapshot reference to a native file input or a visible picker containing exactly one descendant file input. Relative paths are resolved from the invoking Task or Chat workdir; absolute paths are used unchanged. It preserves the supplied file order. For supported live upload controls, the command waits within its existing deadline for the pending change to settle so the next browser command can observe the staged upload. If the visible picker contains no file input or several file inputs, the command fails without clicking the picker or choosing one from elsewhere on the page.

tama browser goal "<objective>" asks Task Machine to choose from the browser actions available in each current page observation and runs those actions within fixed step, request, and elapsed-time limits. Use --start-url <url> for approved navigation and --fields <file|-> to attach bounded JSON from a file or standard input. Relative file paths in file fields are resolved from the invoking Task or Chat workdir before the immutable field-context digest is calculated; absolute paths are used unchanged:

{
  "fields": [
    {
      "name": "Post text",
      "kind": "text",
      "value": "Approved copy"
    },
    {
      "name": "Account password",
      "kind": "credential",
      "credential": "@publisher",
      "field": "password"
    },
    {
      "name": "Hero image",
      "kind": "file",
      "paths": ["/workspace/hero.png"]
    }
  ]
}

Task Machine sends ordinary text and semantic field descriptions to the Browser Goal provider. Credential references resolve just before filling, and file paths remain on the Worker. Credential values, ids, Vault syntax, filenames, and file paths do not reach the backend or provider. The provider selects only finite target-and-field combinations, observed select options, and code-owned key choices. It cannot generate arbitrary browser arguments.

The command keeps the ordinary Browser Run visual history, stops on blocked or ambiguous work, and treats reported completion as a candidate for parent verification rather than proof. Use --id <uuid> with the same objective and unchanged fields to reconnect to durable progress after an interrupted command. Browser Goals remain available when browser access is authorized, including when the Workspace requires managed-AI zero data retention. Low-level browser commands remain available to inspect required inputs, verify results, and intervene.

tama browser fill <ref> --credential @name --field <field> injects an authorized Vault field without printing its value. Later snapshots identify the filled control by its accessible label, credential name, and selected field so another browser action can correlate fields from the same login. The value, credential id, and Vault reference syntax remain absent from snapshots.

Navigation waits for bounded page and rendering readiness. A reload timeout before document readiness is confirmed means only that readiness was not confirmed by the deadline. Use tama browser status or a fresh tama browser snapshot to inspect the current session, then independently verify whether the prior write persisted before retrying reload or writing again. The timeout does not establish whether the new document is inspectable or whether the write was saved or lost.

If reload reaches the document but times out on page load or later rendering readiness, the command still fails and the reached document remains available through the current session. Reload does not retry automatically and always expires earlier element references, so take a fresh snapshot before another element action.

tama browser storage-clear clears cookies for the current browser session, plus local storage, session storage, and IndexedDB scoped to the current page. Its successful response includes a bounded storage_clear object with cookies and site_storage statuses of cleared or unavailable. On opaque pages such as about:blank and browser error pages, cookies can be cleared while page site storage is unavailable. This is an expected successful result. The command never returns storage values or page content. Cookie failures and unrelated page-evaluation failures remain command errors. Unrelated page-evaluation errors state that cookies were cleared before current-page storage failed.

Library, feedback, logs, and MCP

• tama library opens Library discovery. tama library ls lists a path and tama library tree prints its bounded hierarchy. Folder and document results include server-issued Playbook reuse IDs and fingerprints.
• tama feedback automatically attaches the redacted report as evidence to a confident matching active report or creates a new report, then returns only the final Task. Internal candidate reports and duplicate decisions are never exposed. Redact private data before running the command because candidate sanitization does not protect the submitted report.
• tama logs prints local daemon logs for diagnosis.
• tama mcp manages workspace MCP servers for a human operator. tama mcp list becomes assigned-Connector discovery inside a Run and includes each Connector's server-issued Playbook reuse ID and fingerprint. tama mcp add, tama mcp assign, and tama mcp remove remain human management commands and are unavailable to a job-scoped agent. Agents use governed proposals.

Proposal leaf commands

All creation leaves require --rationale: tama propose workspace, tama propose team, tama propose agent-instructions, tama propose skill, tama propose task, tama propose project, tama propose repository, tama propose goal, tama propose workflow, and tama propose document. Run the exact leaf with --help before constructing JSON or flags.

Typed revision leaves are tama propose update agent, tama propose update connector, tama propose update team, tama propose update project, tama propose update goal, tama propose update workflow, tama propose update schedule, and tama propose update playbook.

Each requires the current immutable base version and rejects unknown, ineffective, stale, or cross-workspace changes.

Assignment review

tama tasks assignment-review submits the structured outcome for the current assignment-review Run. It is not a general task edit command. Use its --help schema and submit exactly one reviewed assignment disposition.

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