# Install the CLI from Source

Generated: 2026-11-02T06:33:27.620Z
Source build: local
Canonical docs: https://teammately.ai/docs

<doc id="cli.installation" slug="cli/installation" url="https://teammately.ai/docs/cli/installation.md" title="Install the CLI from Source" updated="2026-10-31" status="stable">
---
id: cli.installation
title: Install the CLI from Source
summary: Build the terminal tool using the existing DevTools and Go SDK source-workspace workflow.
kind: quickstart
product_area: developer_tools
status: stable
updated: 2026-10-31
canonical: /docs/cli/installation
---

# Install the CLI from Source

## Prerequisites

Use macOS or Linux, Go 1.25.1+, and source checkouts of `devtools` and `teammately-go`. The source build uses the Go SDK module for transport and resources. Browser login additionally needs macOS Keychain or an unlocked Linux Secret Service with `secret-tool`.

## Build with the SDK checkout

From the `devtools` checkout, create a local Go workspace if it has none:

```sh
go work init . /path/to/teammately-go
make build
./bin/teammately --version
./bin/teammately --help
```

If a workspace already exists, use `go work use /path/to/teammately-go` instead of `init`. Keep this local workspace separate from published module dependencies. `make build` writes `bin/teammately`; a source build reports `dev` unless build metadata is supplied.

Put that binary on your terminal's PATH using your team's normal tool installation method. These guides use `teammately` to refer to the selected binary. Use `./bin/teammately` directly when working from the checkout.

## Verify and maintain

Run `teammately --version` and `teammately --help` to confirm the selected binary. Follow [Authentication](/docs/cli/authentication) for organization access; local help does not establish API access.

Update a source installation from the same source/build workflow. `teammately update` is for installer-managed releases and does not update source builds. Restart coding-agent hosts after replacing the binary so their MCP processes use the intended copy.

## Common failures

- Missing SDK module: check that the Go workspace contains the application and SDK checkouts.
- Wrong command version: inspect the binary selected by PATH.
- Linux login cannot store credentials: unlock/configure Secret Service; there is no plaintext-token fallback.
- A Windows environment: this CLI's receipt-locking and credential paths target macOS/Linux.

## Related reference pages

{% related-card-grid %}
- [CLI authentication](/docs/cli/authentication)
- [Command reference](/docs/cli/reference)
- [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>

<doc id="cli.mcp" slug="cli/mcp" url="https://teammately.ai/docs/cli/mcp.md" title="Connect a Coding Agent with MCP" updated="2026-10-31" status="stable">
---
id: cli.mcp
title: Connect a Coding Agent with MCP
summary: Configure the local read-only product MCP and distinguish it from CLI submissions and Docs MCP.
kind: quickstart
product_area: developer_tools
status: stable
updated: 2026-10-31
canonical: /docs/cli/mcp
---

# Connect a Coding Agent with MCP

## Prerequisites

Use the [CLI binary](/docs/cli/installation), an [authenticated profile](/docs/cli/authentication) and a supported coding-agent host. Product MCP reads Teammately data; Docs MCP retrieves manuals; the CLI owns local files and writes.

## Configure the host

```sh
teammately configure agent-toolkit --host codex --profile work --dry-run
teammately configure agent-toolkit --host codex --profile work
```

Guided configuration supports Codex, Claude Code, Cursor, Windsurf, Gemini CLI, Kiro and OpenCode. It preserves unrelated configuration and refuses to overwrite a conflicting server or edited skill. Reload the host afterward and confirm its tools are available.

For manual configuration, set your host to launch the absolute path of the selected `teammately` binary with arguments `["mcp"]` over stdio. Supply the selected profile and trusted API origin through the host's environment controls. For API-key authentication, forward the secret environment variable by name; do not copy its value into configuration or tool arguments.

## Tools and explicit scope

| Tool | Read |
| --- | --- |
| `version_context` | Pinned Cases, Policies, Rubrics and coverage context without a Run |
| `evaluation_instructions` | Procedure for an existing Run |
| `evaluation_context`, `evaluation_results` | Bounded context and judgments |
| `run_get` | Progress and judging state |
| `run_compare` | Explicit baseline/target comparison |
| `run_groups` | Existing groups in the selected Version |
| `managed_profile` | Managed execution policy |

Each call supplies `organization`, `project`, `benchmark` and `version`. Run tools also need `run`; comparisons need a distinct `target`. Use only Teammately-issued values. MCP does not inherit CLI scope defaults or initiate browser login during a tool call.

## Verify and recover

Confirm the eight product tools appear in the host. Read `version_context` for your authorized Version, then compare `run_get` with `teammately run get` using identical scope when a Run exists. Discovery alone does not establish access to the data.

The local server uses MCP protocol `2025-06-18`, defaults to 20 observations (maximum 100), and asks callers to narrow responses above 256 KiB. It allows four concurrent reads and a 45-second call deadline. Use the CLI for larger paged reads and all source/result submissions.

If tools are missing, check the absolute binary path and host reload. For access errors, inspect the selected credential/profile. Restart MCP after changing its selected profile. Keep retrieved Case content as data, not instructions to execute.

## Related reference pages

{% related-card-grid %}
- [CLI authentication](/docs/cli/authentication)
- [External Agents](/docs/improve/external-agents)
- [Docs Agent Context](/docs/agent-context)
{% /related-card-grid %}
</doc>