TAZM documentation

Overview

• Quick StartSign in, connect a provider, create a project and start a mission.
• Install the CLIOne file, one command. Needs only Python 3.
• Build your first projectFrom an idea to an approved plan and a running mission.
• CLI referenceEvery tazm command, flag, JSON shape and exit code.
• API referenceStatus of the public developer API.
• Understand evidenceReceipts, evidence items and how to verify what you downloaded.

#What TAZM does

TAZM takes a software project from an approved plan to a verified result. You describe the application or bring an existing codebase, review and approve the plan TAZM writes, and start a mission. TAZM moves the work through its stages and reports the outcome (COMPLETE, REFUSED or BLOCKED) with the evidence behind it.

#Two ways in

• Web. Sign in at tazm.app and use the project screens.
• Command line. Install the tazm CLI. Every command can print one machine-readable JSON object, so it can be scripted and run in CI.

CLI command reference

Every tazm command with its syntax, arguments, flags, JSON output and exit codes, generated from the CLI's own help.

This reference covers tazm 0.5.0. Syntax, arguments and flags on this page are generated from the CLI's own --help output, so they match the release exactly.

#Global flags

Every command accepts:

#JSON output

With --json, every command prints one object and nothing else on standard output:

{"ok": true, "type": "mission_status", "body": {"mission_id": "…", "mission": {…}, "status": "COMPLETE", "outcome": "COMPLETE", "verdicts": […]}}

• ok is true on success and false on any failure.
• type names the result. On failure it is one of usage, refused, not_available, unreachable or error, matching the exit code below.
• body is the command's result; each command lists its body fields.

Without --json, results go to standard output and diagnostics to standard error.

#Exit codes

#Confirmations

Commands that start or change work (project analyze, plan approve, mission start, mission cancel) ask for confirmation on a terminal. Pass --yes to skip the prompt. Without a terminal and without --yes they exit 2 and send nothing; declining exits 3.

#tazm login

Sign in to a TAZM server and save the session for later commands.

#Syntax

tazm login [-h] [--server SERVER] [--json] [--user USER]                  [--password-stdin] [--password-file PATH] [--code-stdin]                  [--code-file PATH]

#Flags

#Behavior

Asks for the user name (unless --user is given), the password and, when the account uses two-factor authentication, the code. Secrets come from a terminal prompt, standard input (--password-stdin, --code-stdin, one line each, in that order) or a file with mode 0600 -- never from arguments or environment variables.

On success the session (cookie and CSRF token) is saved to session.json with mode 0600; see Install the CLI. Without a terminal, a missing password or two-factor code is a usage error.

#Examples

$ tazm login --server https://tazm.app$ tazm login -u [email protected] --password-file ~/.tazm/pw

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is login and body is {server, user, two_factor, …}.

#Exit codes

#tazm logout

End the session on the server and remove the local session file.

#Syntax

tazm logout [-h] [--server SERVER] [--json]

#Flags

#Behavior

The local session is always removed. If the server could not confirm the logout, the command says so: the server session may still be valid until it expires.

#Examples

$ tazm logout

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is logout and body is {was_logged_in, server_logout}.

#Exit codes

#tazm provider connect

Connect an AI provider account to your TAZM account.

#Syntax

tazm provider connect [-h] [--server SERVER] [--json] [--key-stdin]                             [--key-file PATH] [--model MODEL] [--no-probe]                             provider

#Arguments

#Flags

#Behavior

The provider id must be one the server offers; otherwise the command exits 2 and lists the offered ids. When the provider needs a key, it is read from a prompt, --key-stdin or a 0600 --key-file, and is never printed, logged or stored by the CLI. Any echo of the key from the server is shown as [redacted].

After connecting, the provider is probed (skip with --no-probe) and its connection status is shown exactly as the server reports it. A failed probe exits 3; the connection stays in place.

#Examples

$ tazm provider connect claude$ tazm provider connect openai --key-file ~/.tazm/openai-key

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is provider_connect.

#Exit codes

#tazm project create

Create a project, optionally uploading files and a description.

#Syntax

tazm project create [-h] [--server SERVER] [--json]                           [--description DESCRIPTION] [--file PATH]                           name

#Arguments

#Flags

#Behavior

Local inputs are checked first: each --file must be a readable regular file, base names must be unique and the name must not be empty. Nothing is sent if a local check fails.

If a step after creation fails, the error names the project that was created (body.project_id). The project is not deleted.

#Examples

$ tazm project create "Booking app" --description "Online booking for a small clinic"$ tazm project create crm --file spec.md --file roadmap.md

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is project_create.

#Exit codes

#tazm project analyze

Estimate, start or read the analysis of a project.

#Syntax

tazm project analyze [-h] [--server SERVER] [--json] [--estimate-only]                            [--yes] [--result] [--wait] [--interval SECONDS]                            [--timeout SECONDS]                            project

#Arguments

#Flags

#Behavior

Shows the analysis estimate first; --estimate-only stops there. Starting needs --yes or a confirmation that shows the estimate. --result only reads the current analysis.

With --wait, the command polls every --interval seconds while the analysis is queued, pending, running or analyzing. When --timeout runs out it exits 6; the analysis keeps running and --result reads it later. Only an exact REFUSED or BLOCKED status is a refusal.

#Examples

$ tazm project analyze prj_123 --estimate-only$ tazm project analyze prj_123 --yes --wait

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is project_analyze.

#Exit codes

#tazm project status

List your projects, or show one project's activity, spend and usage.

#Syntax

tazm project status [-h] [--server SERVER] [--json] [project]

#Arguments

#Flags

#Behavior

Without an argument, lists projects and your usage. With a project id or exact name, shows that project; an id match wins, a name that matches several projects exits 2 listing their ids, and no match exits 3. Values are shown exactly as the server reports them; spend is an estimate.

#Examples

$ tazm project status$ tazm project status prj_123

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is project_status.

#Exit codes

#tazm plan show

Show a project's plan, coverage, approval state and findings.

#Syntax

tazm plan show [-h] [--server SERVER] [--json] project

#Arguments

#Flags

#Behavior

Only reads, so it exits 0 whatever the approval state is, including BLOCKED or REFUSED, and reports that state verbatim. In human mode it prints the plan, coverage, approval status and one line per finding (id, severity, status, title), then the next command to run.

#Examples

$ tazm plan show prj_123$ tazm plan show prj_123 --json

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is plan_show and body is {project_id, plan, coverage, approval, approval_status, findings}.

#Exit codes

#tazm plan approve

Decide open findings and approve a project's plan.

#Syntax

tazm plan approve [-h] [--server SERVER] [--json]                         [--decide FINDING_ID=DECISION] [--yes]                         project

#Arguments

#Flags

#Behavior

Each --decide must be FINDING_ID=DECISION (ids from tazm plan show); a malformed or repeated decision exits 2 and sends nothing. Decisions are sent in the order given, then the approval.

The CLI never picks decisions for you, and the server alone decides whether the plan can be approved. If a step fails, the error names the findings already decided. Only an exact REFUSED or BLOCKED approval status is a refusal.

#Examples

$ tazm plan approve prj_123 --decide F-2=accept --decide F-5=defer --yes

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is plan_approve and body is {project_id, decisions, approval, status}.

#Exit codes

#tazm mission start

Create and start a mission for a project with an approved plan.

#Syntax

tazm mission start [-h] [--server SERVER] [--json]                          [--mission MISSION_ID] [--yes]                          [project]

#Arguments

#Flags

#Behavior

Give either a project id or --mission MISSION_ID, not both. With a project id, the mission is created and then started; with --mission, an already created mission is started.

If the start fails after the mission was created, the error names the mission (body.mission_id, created: true, started: false) and gives the retry command tazm mission start --mission ID. Nothing is deleted.

#Examples

$ tazm mission start prj_123 --yes$ tazm mission start --mission msn_456 --yes

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is mission_start and body is {project_id, mission_id, mission, created, start, status}.

#Exit codes

#tazm mission status

Show a mission's status and verdicts, optionally waiting for it to finish.

#Syntax

tazm mission status [-h] [--server SERVER] [--json] [--wait]                           [--interval SECONDS] [--timeout SECONDS]                           mission

#Arguments

#Flags

#Behavior

With --wait, polls every --interval seconds while the mission is queued, pending, starting, running or stopping; any other state ends the wait and is shown verbatim. When --timeout runs out the command exits 6 and the mission continues on the server.

outcome is set only when the status is exactly COMPLETE, REFUSED or BLOCKED; otherwise it is null.

#Examples

$ tazm mission status msn_456$ tazm mission status msn_456 --wait --json

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is mission_status and body is {mission_id, mission, status, outcome, verdicts}.

#Exit codes

#tazm mission logs

Print a mission's timeline, optionally following the live stream.

#Syntax

tazm mission logs [-h] [--server SERVER] [--json] [--follow]                         [--idle-timeout SECONDS]                         mission

#Arguments

#Flags

#Behavior

Prints the timeline. With --follow it then reads the live event stream and prints each event as it arrives, until the server closes the stream. --idle-timeout (default 300 seconds) limits how long it waits without data. With --json, one object is printed at the end.

#Examples

$ tazm mission logs msn_456$ tazm mission logs msn_456 --follow

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is mission_logs and body is {mission_id, timeline, followed, stream}.

#Exit codes

#tazm mission evidence

Show a mission's receipt and download its evidence items.

#Syntax

tazm mission evidence [-h] [--server SERVER] [--json] [--ref REF]                             [--all]                             mission

#Arguments

#Flags

#Behavior

Shows the mission's receipt, which lists its evidence items by reference. --ref REF (repeatable) downloads the named items in the order given; --all downloads every item the receipt lists. --ref and --all cannot be combined.

Each downloaded item is reported as {ref, content_type, bytes, sha256}. The SHA-256 is computed by the CLI from the bytes it received. See Evidence.

#Examples

$ tazm mission evidence msn_456$ tazm mission evidence msn_456 --all --json

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is mission_evidence and body is {mission_id, receipt, status, refs, evidence}.

#Exit codes

#tazm mission cancel

Ask the server to stop a mission.

#Syntax

tazm mission cancel [-h] [--server SERVER] [--json] [--yes] mission

#Arguments

#Flags

#Behavior

Sends the stop request after confirmation (or --yes). The CLI does not decide that the mission has stopped: run tazm mission status ID --wait to see what the server reports.

#Examples

$ tazm mission cancel msn_456 --yes$ tazm mission status msn_456 --wait

#JSON output

With --json the command prints one object {"ok", "type", "body"}; on success type is mission_cancel and body is {mission_id, result, status}.

#Exit codes

Evidence Live

What TAZM records to back a result, how to retrieve it, and how to check that what you downloaded is what the server holds.

#Why evidence

A builder saying "done" is not accepted as proof. In TAZM, every requirement carries the evidence behind it, and a claim that has no evidence is shown as exactly that. A mission's result is backed by records you can retrieve and check, not by a summary you have to trust.

#Mission outcomes

The CLI recognises three outcomes, reported exactly as the server records them. Any other status is shown as-is and is not treated as an outcome.

The CLI never infers an outcome: outcome is set only when the server's status is exactly one of these three values. See tazm mission status.

#The receipt

Each mission has a receipt. It records the mission's status and lists its evidence items by reference (ref). Retrieve it with:

$ tazm mission evidence msn_456

Reading the receipt changes nothing, so the command succeeds whatever the mission's status is, and shows that status verbatim.

#Evidence items

Download one or more items by reference, or every item the receipt lists:

$ tazm mission evidence msn_456 --ref ev-tests$ tazm mission evidence msn_456 --all --json

Each downloaded item is reported as:

#Verifying what you downloaded

Because sha256 is computed by the CLI over the bytes it received, you can record it and compare it later with a fresh download. Matching hashes mean you are looking at the same evidence.

$ tazm mission evidence msn_456 --all --json > evidence-1.json$ tazm mission evidence msn_456 --all --json > evidence-2.json

Compare the sha256 values of each ref in the two files: an item whose hash differs is not the same item.

#Verdicts

tazm mission status returns the mission's verdicts together with its status. They are shown exactly as the server records them.

API Not available

Status of the public TAZM developer API.

#What this means

• There are no developer API keys or access tokens to issue today.
• The HTTP endpoints the TAZM web app and CLI use internally are not a public API. They are not documented here, they can change without notice, and they are not supported for direct use.

#Automate with the CLI instead

Everything the API would be used for today (creating projects, approving plans, starting missions, reading status, logs and evidence) is available through the tazm CLI. With --json, every command prints exactly one machine-readable object and exits with a documented code, so it can be used from scripts and CI.

$ tazm mission status msn_456 --wait --json

See the command reference for the JSON shape and exit codes.

#When the API ships

This section will document authentication, projects, plans, missions, evidence, errors, idempotency, rate limits and response objects for the public API. Until then, it lists nothing that is not available.