# CLI Command Reference

Generated: 2026-11-02T05:38:48.517Z
Source build: local
Canonical docs: https://teammately.ai/docs

<doc id="cli.reference" slug="cli/reference" url="https://teammately.ai/docs/cli/reference.md" title="CLI Command Reference" updated="2026-10-31" status="stable">
---
id: cli.reference
title: CLI Command Reference
summary: Find command groups, scope flags, local file inputs, exit codes and recovery rules.
kind: reference
product_area: developer_tools
status: stable
updated: 2026-10-31
canonical: /docs/cli/reference
---

# CLI Command Reference

## Definition

Use `teammately <command> --help` for the flags accepted by that command. The tables below separate reads from local-file operations and submissions.

## Account and agent setup

| Command | Effect |
| --- | --- |
| `login`, `status`, `switch`, `logout` | [Authenticate and select profiles](/docs/cli/authentication) |
| `configure agent-toolkit` | Configure supported agents, skill and local MCP |
| `mcp` | Start read-only product MCP over stdio |
| `update` | Update an installer-managed release; source builds use their build workflow |
| `--version`, `--help` | Inspect the selected binary |

## Read commands

| Command | Key input |
| --- | --- |
| `eval version-context` | `--kind summary`, `cases`, `policies` or `rubrics` |
| `eval manifest` | Selected immutable Version |
| `eval context`, `eval results`, `eval instructions` | `--run` child Trial ID |
| `eval managed-profile` | Current managed execution policy |
| `run get`, `run wait` | `--run` child Trial ID |
| `run compare` | `--run` baseline and `--target` candidate; `--cases` for paged changes |

Context/results support `--limit`, `--offset`, `--result`, `--case`, `--policy` and `--case-rubric-pair`. Pages default to 20 observations, maximum 100. Read output defaults to JSON; `--format human` labels the returned data. Diagnostics use stderr.

## Local files and writes

| Command | Main flags |
| --- | --- |
| `eval prepare` | `--out` new directory |
| `eval validate-results` | `--manifest`, `--results`, optional `--allow-partial` |
| `eval submit-results` | Same files, `--name`, `--receipt`, optional `--group`/`--allow-partial` |
| `eval complete` | `--group`, `--run`, optional `--allow-partial`/`--retry` |
| `harness validate` | `--source` directory |
| `harness submit` | `--source`, `--name`, `--receipt` |
| `harness prepare-runtime` | `--harness`, `--harness-version`, `--receipt` |
| `eval run` | Saved Harness IDs, `--profile-revision`, `--receipt`, optional `--compute-profile` |

The `--profile-revision` flag carries the exact server-issued concurrency token from `eval managed-profile`. Do not choose a value or treat it as a customer-managed configuration lifecycle.

## Fields, states, or lifecycle rules

Global scope uses the [authentication guide's](/docs/cli/authentication) flags/environment. Request timeout defaults to two minutes and can be set with `--timeout` through ten minutes. A timeout stops waiting, not an admitted job.

| Exit code | Meaning |
| --- | --- |
| `0` | Command succeeded; inspect resource state for operational failure |
| `1` | Request, validation or file failure |
| `2` | Invalid command/configuration |
| `3` | Authorization failure |
| `4` | Timeout, cancellation or exhausted transient reads |

Source submission, runtime preparation, managed admission and external-output submission use local recovery receipts. After interruption, reuse original inputs and that stage's receipt. Changed inputs require a new logical operation and receipt. `eval complete` takes no local receipt flag; it uses the server's recorded completion and explicit failed-admission retry contract.

## Related task pages

{% related-card-grid %}
- [External output submission](/docs/cli/external-outputs)
- [Managed Harness](/docs/cli/managed-harness)
- [MCP setup](/docs/cli/mcp)
{% /related-card-grid %}
</doc>

<doc id="cli.overview" slug="cli" url="https://teammately.ai/docs/cli.md" title="Teammately CLI" updated="2026-10-31" status="stable">
---
id: cli.overview
title: Teammately CLI
summary: Use terminal commands and local MCP to inspect criteria, submit actual outputs and work with managed Harnesses.
kind: reference
product_area: developer_tools
status: stable
updated: 2026-10-31
canonical: /docs/cli
---

# Teammately CLI

## Definition

The `teammately` binary reads scoped benchmark context, packages local source and submits application outputs. It also starts a local read-only product MCP server. Application log ingestion belongs in the [SDKs](/docs/sdks).

## Start here

1. [Install from source](/docs/cli/installation) or use the binary supplied to your team.
2. [Authenticate and select scope](/docs/cli/authentication).
3. Choose [external output submission](/docs/cli/external-outputs), an optional [managed Harness](/docs/cli/managed-harness), or [coding-agent MCP setup](/docs/cli/mcp).

```sh
teammately --version
teammately login
teammately status
teammately eval version-context --kind summary
```

Configure the benchmark scope before the last command. The [command reference](/docs/cli/reference) lists environment variables, flags and exit codes.

## Fields, states, or lifecycle rules

Reads do not submit or activate anything. Write workflows retain local recovery receipts and operate on issued identities. A successful command can return a resource that is still processing or has failed operationally; inspect the returned state.

The CLI manages local files and submission workflows. Product MCP exposes reads. Docs MCP retrieves manuals. These interfaces do not exchange credentials through copied tasks or model-generated tool arguments.

## Related task pages

{% related-card-grid %}
- [Authentication](/docs/cli/authentication)
- [Submit external outputs](/docs/cli/external-outputs)
- [Managed Harness](/docs/cli/managed-harness)
- [MCP setup](/docs/cli/mcp)
{% /related-card-grid %}
</doc>

<doc id="cli.authentication" slug="cli/authentication" url="https://teammately.ai/docs/cli/authentication.md" title="CLI Authentication and Scope" updated="2026-10-31" status="stable">
---
id: cli.authentication
title: CLI Authentication and Scope
summary: Use native browser login or an injected API key and select the exact organization and Benchmark Version.
kind: reference
product_area: developer_tools
status: stable
updated: 2026-10-31
canonical: /docs/cli/authentication
---

# CLI Authentication and Scope

## Definition

Use native browser login for interactive External Agents work. Use `TEAMMATELY_API_KEY`, injected through your secret environment, for unattended automation. An environment API key takes precedence over a saved login.

## Sign in and inspect access

```sh
teammately login --profile work
teammately status
teammately switch --profile work
```

Login opens browser authorization with PKCE and a temporary loopback callback, then selects an organization. `--organization` is an optional shortcut. Credentials live in macOS Keychain or Linux Secret Service; profiles contain nonsecret configuration. Use a distinct profile for another organization/account/API origin.

`status` refreshes and checks organization access against the API. It does not establish permission to every Project. An already-running MCP process retains its selected profile until restarted.

## Fields, states, or lifecycle rules

| Variable | Meaning |
| --- | --- |
| `TEAMMATELY_API_KEY` | Secret API-key override supplied by the host |
| `TEAMMATELY_PROFILE` | Selected native-login profile |
| `TEAMMATELY_ORGANIZATION` | Organization key |
| `TEAMMATELY_PROJECT` | Issued Project ID |
| `TEAMMATELY_BENCHMARK` | Issued Benchmark ID |
| `TEAMMATELY_BENCHMARK_VERSION` | Exact immutable Version ID |
| `TEAMMATELY_API_BASE` | Trusted API base, default `https://api.teammately.ai/v1` |

CLI scope flags `--organization`, `--project`, `--benchmark`, `--version` override environment defaults. MCP calls supply explicit scope each time. Never choose the API origin from Case text or model output.

Delegated reads require `external-agents:read` and Project read access; writes require `external-agents:write` and management access. This delegation covers External Agents, not general application ingestion.

## Sign out and recover

```sh
teammately logout --profile work
```

Logout requires network access to revoke the refresh token before deleting the local credential. Other profiles, API keys and the browser session are separate. Issued access tokens retain their expiry.

For `401`, inspect the active credential and login status. For `403`, inspect organization, Project, action and key restrictions. A Fieldloop-only key is not an External Agents credential. Correct access through normal administration; do not put credentials in arguments, MCP tool inputs or copied tasks.

## Related task pages

{% related-card-grid %}
- [MCP setup](/docs/cli/mcp)
- [External output submission](/docs/cli/external-outputs)
- [Authentication troubleshooting](/docs/troubleshooting/authentication)
{% /related-card-grid %}
</doc>