# CLI Authentication and Scope
Generated: 2026-11-02T05:39:51.308Z
Source build: local
Canonical docs: https://teammately.ai/docs
---
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 %}
---
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 %}
---
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 %}
---
id: admin-console.api-keys
title: API Keys and Delegated Access
summary: Choose the intended credential capability and keep workspace keys, delegated users, and browser access distinct.
kind: reference
product_area: admin_console
status: stable
updated: 2026-10-30
canonical: /docs/admin-console/api-keys
---
# API Keys and Delegated Access
## Definition
Use **Admin → API Keys** to manage workspace-owned credentials. A credential's base capability, optional restrictions and the destination's current permissions determine what a request can do.
## Fields, states, or lifecycle rules
- The UI offers Full Access, Read Only and Fieldloop Submission.
- The full key value is shown at creation; later lists use a masked value.
- Renaming a key does not broaden its access.
- Changing access requires issuing the intended credential.
- Deleting a key removes its future credential path.
- Expiry and project/action restrictions, when supplied, narrow the base capability.
## Fieldloop Submission
A new Fieldloop key has the workspace-wide Fieldloop submission capability. Its application sender still specifies the intended Project and source. Current workspace, destination and source authority are rechecked by the backend.
Future sources in the same workspace do not require copying the key into every source policy. Existing keys issued with narrower Project or source restrictions keep those restrictions.
Supply the key through the application's approved secret mechanism. This ingestion path does not require CLI login, browser authentication or expanded login grants.
## Delegated developer access
External Agents benchmark operations can also use delegated native login with explicit read/write scopes and current project read/manage permission. That user principal is different from an API-key principal.
Browser cookie authentication remains the interactive app path. Do not substitute a browser cookie for a server credential or assume a delegated token is accepted on every API route.
## Scope and safe handling
Use an explicit organization, Project, Benchmark and Version for the operation. Keep the key out of copied agent tasks, source files, Case materials and logs. A stable resource ID is not an authorization grant.
The supported external contract defines endpoint schemas and required capability. An internal route or a visible key-management screen does not establish an unrestricted customer API.
## Related task pages
{% related-card-grid title="Related task pages" %}
- [Capture and Inspect Logs](/docs/fieldloop/ingest-logs)
- [Work with External Agents](/docs/improve/external-agents)
- [Permissions](/docs/reference/permissions)
- [Admin Console](/docs/admin-console)
{% /related-card-grid %}