> ## Documentation Index
> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Terminal Authentication
Author(s): [anna239](https://github.com/anna239)
## Elevator pitch
> What are you proposing to change?
Add a typed terminal authentication method so a Client can run the configured
Agent program interactively for login, then reconnect to the Agent after the
login flow succeeds.
## Status quo
> How do things work today and what problems does this cause? Why would we change things?
Agents use several authentication flows. Some can handle login over ACP, while
others require users to interact with the Agent's terminal UI. The baseline
`agent` authentication method does not tell a Client that it must launch an
interactive program, so users may need to leave the Client and complete setup
manually.
## What we propose to do about it
> What are you proposing to improve the situation?
Add a `terminal` authentication method. A supporting Client launches the same
configured Agent program in an interactive terminal, adding arguments and
environment variables supplied by the Agent. After the terminal flow succeeds,
the Client reconnects and reinitializes the ACP Agent.
Terminal authentication is an out-of-band process. The Client does not pass a
terminal method to v1 `authenticate` or v2 `auth/login`.
## Shiny future
> How will things play out once this feature exists?
Users can complete an Agent's interactive login flow without leaving their
Client. Agents describe how to enter that flow without knowing the
Client-specific path or command used to launch them.
## Implementation details and plan
> Tell me more about your implementation. What is your detailed implementation plan?
### Terminal authentication method
The `terminal` discriminator identifies a terminal authentication method. The
descriptor includes:
* `args` (optional, default `[]`): additional arguments for the configured Agent
program.
* `env` (optional, default empty): additional environment variables for the
terminal process. Descriptor values override same-named variables in the base
launch configuration. In v2, every `env` entry **MUST** have a unique `name`.
The identifier and `env` wire shapes differ between protocol versions.
```json v1 theme={null}
{
"id": "agent-login",
"name": "Log in from the terminal",
"description": "Open the Agent's interactive login flow",
"type": "terminal",
"args": ["--login"],
"env": {
"ACP_INTERACTIVE_LOGIN": "1"
}
}
```
```json v2 theme={null}
{
"methodId": "agent-login",
"name": "Log in from the terminal",
"description": "Open the Agent's interactive login flow",
"type": "terminal",
"args": ["--login"],
"env": [
{
"name": "ACP_INTERACTIVE_LOGIN",
"value": "1"
}
]
}
```
The descriptor cannot specify a command. The Client constructs the terminal
invocation from the same configured Agent program and base launch configuration
used for the ACP connection, then appends `args` and applies `env`. This keeps
the descriptor independent of Client-specific installation paths and prevents
the Agent from selecting an unrelated program.
### Client capability
Clients opt in because terminal authentication requires Client-side process and
terminal support.
```json v1 theme={null}
{
"clientCapabilities": {
"auth": {
"terminal": true
}
}
}
```
```json v2 theme={null}
{
"capabilities": {
"auth": {
"terminal": {}
}
}
}
```
A Client advertises this capability only when it can reproduce the configured
Agent invocation in an interactive terminal. In particular, a Client connected
to an Agent over a remote transport must omit the capability unless it can
launch that same Agent program in the Agent's execution environment.
An Agent may advertise a `terminal` authentication method only when the Client
advertised the corresponding capability.
### Login flow
1. The Client initializes the ACP connection and receives a `terminal`
authentication method.
2. When the user selects it, the Client launches a separate interactive process
using the configured Agent program and base launch configuration, plus the
descriptor's `args` and `env`.
3. The Client presents the terminal to the user and waits for the process to
exit. Exit status zero signals success; a non-zero status, termination
without an exit status, or cancellation signals failure.
4. On success, the Client reconnects and reinitializes the ACP Agent, then
retries the operation that required authentication.
Agents **SHOULD** provide arguments that enter a login-only flow and exit after
the flow completes. ACP does not define an output pattern or other in-band
success signal. Clients may recognize implementation-specific signals as an
extension, but Agents cannot require that behavior for interoperability.
The Client **MUST NOT** pass the terminal method to v1 `authenticate` or v2
`auth/login`: the interactive terminal process is not the ACP connection.
In v2, advertising any authentication method requires the Agent to implement
both `auth/login` and `auth/logout`, preserving the baseline authentication
surface rule. The standard `agent` type uses `auth/login`; `terminal` does not,
so Clients never pass a terminal method ID to that endpoint.
## Frequently asked questions
> What questions have arisen over the course of authoring this document or during subsequent discussions?
### What alternative approaches did you consider?
The proposal originally included an `env_var` method that asked the Client to
collect credentials and restart the Agent with new environment variables. That
model assumes the Client owns the Agent process and does not generalize to
remote transports. Agents using this former experimental method should replace
it with `agent` or `terminal` authentication.
Authentication setup could also be included in an Agent's registry declaration,
making it static rather than negotiated. See the [Registry
RFD](https://github.com/agentclientprotocol/agent-client-protocol/pull/289).
Structured credential collection could instead use an elicitation flow. That
keeps user input inside the Agent's protocol-driven authentication logic rather
than giving the Client special knowledge of environment variables.
## Revision history
The original authentication RFD also discussed elicitation. That material was
removed and moved to a separate proposal.
* 2026-07-27: Removed the remaining unstable `env_var` types and made the Rust
SDK decode legacy descriptors as `agent` in both protocol versions.
* 2026-07-24: Moved terminal authentication to Preview, defined it as an
out-of-band launch and reconnect flow, removed `env_var` from v2, and retained
the unstable v1 variant for compatibility.
* 2026-03-09: Removed `auth_methods` from the Error type.
* 2026-03-03: Changed `env_var` from a single `varName` to a structured `vars`
array of `AuthEnvVar` objects and simplified the field name from `varName` to
`name`.
* 2026-02-27: Updated the proposal to reflect the implementation.
* 2026-01-14: Incorporated Core Maintainer feedback.