earshotby raegentGet earshot
Documentation v0.3.2

Start exploring

OverviewStartInstallation and updatingStartAuthentication and onboardingStartFirst runStartTroubleshootingStartWhy Earshot listensCore conceptsScope and editable plansCore conceptsPermissions and trust modesCore conceptsSteering, sessions, rewind, fork, and undoCore conceptsMemory, context, cost, and verificationCore conceptsCLI referenceUsing EarshotProviders and modelsUsing EarshotHeadless outputUsing EarshotEditor integration with ACPUsing EarshotCompatibility guaranteesUsing EarshotMCP serversExtendingIn-process extensionsExtendingSkills and slash commandsExtendingHooks and subagentsExtendingAdding a providerExtendingArchitectureInternals and projectPerformance baselinesInternals and projectRoadmap and current statusInternals and projectRelease and platform QAInternals and project
↑ ↓ navigate · Enter openEsc close
Earshot / Start

Authentication and onboarding

Choose a provider, verify a model, and manage credentials.

Reviewed for 0.3.2 · Latest documentation

Authenticate#

Skip this section on a first run in a real terminal: starting earshot with no credentials configured opens the TUI into onboarding — pick a provider, search and select one of its model IDs, then sign in or paste a key. That exact model is checked with one live call before you land in your first turn. Nothing is printed or logged: the key goes straight into the same auth.json earshot auth login writes to, 0600 and atomic. --no-onboarding restores the old dead end for scripts and CI, and earshot -p and earshot acp never onboard — a script has nobody to answer a prompt, so a missing credential there still exits 3 immediately, same as always.

To set up credentials ahead of time instead, or for a provider onboarding does not ask about first:

earshot resolves credentials in a fixed order, first match wins:

  1. A CLI flag (--api-key)
  2. The provider's environment variable
  3. ~/.config/earshot/auth.json (mode 0600 on POSIX)
  4. Provider-native ambient credentials — the AWS credential chain, Google ADC

For most providers, setting one environment variable is all you need:

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...
export OPENROUTER_API_KEY=sk-or-...

Every provider and its variables: Providers.

Bedrock and Vertex use ambient credentials — if aws or gcloud already works on your machine, earshot works too. No key to set.

Local runtimes need no credentials at all:

ollama serve   # earshot discovers whatever you have pulled
Something unclear?Suggest a correction on GitHub ↗