Documentation

CLI Authentication

Learn how the Kindship CLI authenticates with your account using secure OAuth with PKCE.

The Kindship CLI uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) for secure authentication to your Kindship account. This ensures your credentials are never stored in plain text.

How It Works

  1. CLI generates PKCE parameters — A cryptographic code verifier and challenge
  2. Browser opens for login — You authenticate using your existing Kindship account
  3. Secure callback — The auth code is exchanged for a CLI token
  4. Token stored locally — Credentials saved to ~/.kindship/config.json with strict permissions

Login

kindship login

This opens your default browser to authenticate. If the browser doesn't open automatically, the URL is printed to the terminal.

This login authenticates the Kindship CLI itself. It does not automatically authenticate Claude Code, Codex, Gemini CLI, or OpenCode for agent execution. Those provider credentials are managed separately inside the web workspace.

Custom API URL

For development or self-hosted instances:

kindship login --api-url https://your-instance.com

Or set the environment variable:

export KINDSHIP_API_URL=https://your-instance.com
kindship login

Token Management

Check Current Session

kindship whoami

Shows your authenticated email and active agent.

Logout

kindship logout

Revokes your current token.

Logout from All Devices

kindship logout --all

Revokes all tokens associated with your account.

Token Storage

Tokens are stored in ~/.kindship/config.json with 0600 permissions (read/write for owner only).

{
  "token": "ksh_...",
  "token_id": "uuid",
  "token_expiry": "2025-02-02T...",
  "user_id": "uuid",
  "user_email": "[email protected]",
  "api_base_url": "https://kindship.ai"
}

Token Expiration

CLI tokens expire after 14 days. When expired, simply run kindship login again. If you have an active browser session with Kindship, re-authentication is instant.

Security Best Practices

  • Never share your token — Treat it like a password
  • Use kindship logout --all — If you suspect compromise
  • Check permissions — Ensure ~/.kindship/config.json has 0600 permissions

Provider Credentials For Agent Execution

When an agent uses a coding CLI, Kindship may also need access to the upstream provider behind that CLI.

Supported Coding CLIs

Kindship can manage execution credentials for:

  • Claude Code
  • Codex
  • Gemini CLI
  • OpenCode

Where To Manage Them

Open an agent in the web app and use:

  • CLI Authentication to see the current status for each supported coding CLI
  • Manage Credentials to add or update provider access
  • Inner Loop to choose which CLI and model the agent should actually use

What The Status Means

The workspace distinguishes a few different states:

  • Not reachable — The container cannot currently be checked
  • Not installed — That coding CLI is unavailable in the agent environment
  • Not configured — No usable credential is currently available
  • Authorized — The credential exists and passed a live auth check
  • Kindship shared — The agent is using Kindship-managed credentials instead of your own, when your account is eligible for that fallback
  • Requires your credentials — The agent is configured not to use a shared fallback and needs provider access you control

Device Auth And API Keys

Some CLIs support more than one authentication pattern.

  • Codex can use device auth or an API key, depending on how you prefer to connect it
  • Other CLIs may rely on account-level or agent-specific credentials
  • The workspace shows whether a credential is agent-specific, account-level, or Kindship-managed, which helps explain why one agent can run while another cannot
  • An agent can require your own provider credentials, which prevents it from relying on Kindship-managed fallback credentials when you want execution tied to credentials you control

When Dispatch Is Blocked

If an agent cannot run because provider access is missing or disallowed, the workspace should explain the credential requirement rather than failing silently.

Common checks:

  • Open the agent workspace and review CLI Authentication
  • Confirm the selected Inner Loop CLI has usable credentials
  • If the agent requires your own credentials, add them instead of relying on a shared fallback
  • If a shared provider is temporarily unavailable, wait for the provider state to recover or switch the agent to credentials you control

Why This Is Separate From kindship login

kindship login proves that you are allowed to use Kindship. It does not prove that a specific coding provider will accept work on behalf of a specific agent.

That separation is intentional:

  • Kindship account auth controls access to your account and agents
  • Provider auth controls whether an agent can actually execute through a given coding CLI
  • Inner loop settings decide which authenticated CLI and model the agent should prefer during execution