feat(docs, auth): Document Headless/Remote Authentication and Support CI/CD

Title: feat(docs, auth): Document Headless/Remote Authentication and Support CI/CD

Labels: documentation, feature-request, enhancement, authentication, onboarding, cli, security

1. Problem Statement

The current authentication flow for Claude Code, initiated via claude /login, relies on an OAuth process that requires opening a local web browser. This presents a significant setup blocker for two distinct but related groups of professional developers:

1. Developers in Interactive Headless Environments: Those working on a remote server via SSH, inside a Docker container, or using cloud-based IDEs (e.g., GitHub Codespaces, Gitpod) where a local GUI browser is not available.
2. Automation in Non-Interactive Environments: Automated systems like CI/CD pipelines (e.g., GitHub Actions, Jenkins) that need to authenticate programmatically without human intervention.

The standard login flow only addresses local GUI-based development, creating friction that forces users to find complex workarounds, abandon the tool, or bypass it in automated workflows.

2. Proposed Solutions

We propose creating a dedicated documentation page (e.g., "Authentication for Advanced Environments") that provides clear, step-by-step instructions for these scenarios. This guide should detail two documented workarounds for interactive sessions and propose a new feature for non-interactive automation.

---

Method 1: Interactive Login via SSH Port Forwarding

This method allows a user connected via SSH to securely forward the CLI's authentication port from the remote machine to their local machine.

Suggested Documentation Steps:

1. On your local machine, connect to your remote server using ssh -L to forward the port. The CLI will inform you of the correct port when you run the login command.

``bash
# On your local machine, replace 8080 with the port number
# printed by the claude /login command on the remote server.
ssh -L 8080:localhost:8080 user@remote-server.com
``

1. In the remote SSH session, run clade /login. Look for output from the CLI indicating it has started a local web server, such as:

Please open this URL in your browser to complete authentication: http://localhost:8080/...

1. Copy the full http://localhost:8080/... URL and paste it into the browser on your local machine.
2. Complete the authentication flow. The token will be securely transmitted back to the claude instance running on your remote machine.

Important Considerations: This method may not work if your corporate firewall or the remote server's SSH configuration (AllowTcpForwarding no) explicitly blocks TCP port forwarding.

---

Method 2: Interactive Login via Secure Credential Transfer

This method involves authenticating on a local machine and then securely transferring the resulting credential file to the remote environment.

Prerequisite: This method assumes the authentication token in auth.json is a self-contained bearer token that is not bound to a specific machine or IP address.

Suggested Documentation Steps:

1. On your local machine (where you have a browser), install and run claude /login.
2. This will create a credential file at ~/.config/claude-code/auth.json.
3. Securely transfer this file to the corresponding directory on your remote machine or container.

Example for a remote SSH server:
```bash
# From your local machine:
# 1. Ensure the target directory exists on the remote machine
ssh user@remote-server.com "mkdir -p ~/.config/claude-code"

# 2. Securely copy the credential file
scp ~/.config/claude-code/auth.json user@remote-server.com:~/.config/claude-code/auth.json
``
**Example for a Docker container (Recommended Practice):**
For reproducible environments, mount the credential file as a read-only volume.
`bash
# Run your container with the auth file mounted
docker run -v ~/.config/claude-code/auth.json:/root/.config/claude-code/auth.json:ro -it my-dev-image
`
*(Note: The user home directory, e.g., /root/, may vary. Using a volume is safer than docker cp` as it avoids leaving credentials inside a committed container image.)*

1. Once the file is in place, claude will be authenticated on the remote machine.

### Security: Token Revocation and Management Warning: The auth.json file contains a sensitive credential. Treat it like a password. If a remote machine or environment containing this file is ever compromised, you must immediately invalidate the token. 1. Go to your Anthropic Account Settings page: claude.ai/settings/account 2. Navigate to the "Active Connections" or "API Keys" section. 3. Locate and revoke the session or key associated with the compromised machine.

---

Method 3: Non-Interactive Authentication for CI/CD

The methods above solve for interactive sessions but not for automated environments. We propose adding support for non-interactive authentication via an API key, which is the standard practice for CI/CD tools.

Proposed Implementation:

1. Generate a Service Token: Users should be able to generate a long-lived API key or service account token from their Anthropic Console account settings.
2. Authentication via Environment Variable: The CLI should automatically authenticate if a specific environment variable is present.

``bash
# The CLI detects this variable and uses it to authenticate,
# bypassing the interactive OAuth flow entirely.
export CLAUDE_CODE_API_KEY="anth-sk-..."
claude -p "Summarize the changes in this commit."
``
This method is secure, widely understood, and integrates perfectly with secrets management systems in all major CI/CD platforms (e.g., GitHub Actions Secrets, GitLab CI/CD Variables).

3. Benefits

• Unblocks Key User Segments: Directly solves a critical setup hurdle for developers in modern remote, containerized, and automated environments.
• Improves Onboarding Experience: Drastically reduces the time-to-first-value for a large segment of professional users.
• Supports Enterprise & Automated Workflows: Aligns Claude Code with industry-standard practices for both interactive remote development and non-interactive CI/CD automation.
• Enhances Security Posture: Providing a clear, documented path for non-interactive auth (Method 3) prevents users from storing personal, interactive-use credentials in insecure CI environments.

4. Suggested Documentation Location

• Primary Location: A new, dedicated page such as "Authentication for Advanced Environments" under the "Setup" or "IAM & Access Control" section.
• Cross-Reference: Add links from the Quickstart, Troubleshooting, and GitHub Actions pages to guide users who encounter these specific authentication challenges.