Set up AgentID from your terminal

Run one command from an existing application. The CLI detects or asks for the auth provider, uses your browser only to authorize registration, writes the credentials locally and finishes configuration in the terminal.

On this page

Run the quickstart#

Use Node.js 20 or newer, change into the application you want to configure and run:

terminal

cd your-app
npx @agentmail/agentid-cli init

If the project contains one supported provider, the CLI selects it. If detection is ambiguous or unavailable, choose a provider from the terminal. Hosted providers may open their own browser or device login when their CLI session is missing.

Watch out. Auth0 and Supabase setup expects an existing application or project. Better Auth and Auth.js setup expects the library and a server config to exist already. The AgentID CLI configures those resources; it does not invent the application around them.

What the command does#

Detect: Find the local provider, project identity, callback URL and credential destination.
Authorize: Open the AgentID console, use its current browser session and ask the active organization to approve this exact relying party.
Register: Create the OAuth client after approval and return its credentials directly to the waiting CLI.
Store: Write AGENTID_CLIENT_ID, AGENTID_CLIENT_SECRET and an immutable project binding to the nearest .env.local.
Configure: Create or update the supported provider connection or managed local config, then validate OIDC discovery and callback settings.

Hosted-provider sign-in stays disabled by default. Add --enable-sso only when the connection should become available to users immediately. Better Auth and Auth.js have no hosted enablement switch; add their AgentID sign-in button when the application is ready.

Supported providers#

Clerk: Selects a Clerk application and instance, registers AgentID and configures the custom OAuth connection.
Auth0: Selects an existing login-capable application and creates the AgentID custom social connection with PKCE, profile mapping and branding.
Supabase: Selects an existing project and configures custom:agentid with discovery, claim mappings and branding.
Better Auth: Finds the installed server config and adds a guarded, CLI-managed generic OAuth provider block.
Auth.js v4: Finds a NextAuth server config and adds a guarded, CLI-managed OAuth provider with PKCE, nonce and ES256 metadata.
Other OIDC: Registers the supplied application name and callback URLs, then leaves provider-specific wiring to the application.

Provider-specific behavior and manual fallbacks live in the provider guides.

Choose owner scopes only when needed#

Interactive setup offers a picker. Press Enter for standard agent identity: openid, email and profile. Add the owner scopes only when the application needs information about the human behind the agent.

terminal

# include the owner's email
npx @agentmail/agentid-cli init --owner-email

# include the owner's name and email
npx @agentmail/agentid-cli init --owner-name --owner-email

--owner-name requests owner_profile; --owner-email requests owner_email. The agent’s signing credential remains the final gate, so requesting a scope does not guarantee that every sign-in grants it.

Verify without changing anything#

terminal

npx @agentmail/agentid-cli doctor

Doctor checks detection, callbacks, credential integrity, Git and file-permission safety, project binding, AgentID discovery and keys, and the supported provider configuration. It reports every check in one pass and exits with status 1 when a required check fails.

CI or agents

npx @agentmail/agentid-cli doctor --json

JSON mode never prompts or opens a login flow. It uses stable check IDs and preserves the same exit-status behavior for CI.

Provide metadata directly#

For a noninteractive or generic OIDC project, provide the relying-party metadata instead of using project detection:

terminal

npx @agentmail/agentid-cli init \
  --name Acme \
  --redirect-uri https://acme.example/auth/callback

Repeat --redirect-uri to register additional callbacks. Browser approval is still required; registration has no unattended bypass.

Recover without starting over#

The browser did not open: Rerun with --no-open and open the printed URL in a browser on the same machine. Keep the terminal running so its one-time loopback callback can finish.
Approval finished but the terminal is waiting: Return to the original terminal and wait briefly. If it does not resume, rerun init. A request that never completed expires automatically. If the client exists in the AgentID console but credentials were not stored, delete that incomplete client before retrying.
Provider configuration failed after credentials were stored: Fix the provider login or reported configuration conflict and rerun the same init command with the same owner-scope options. The CLI reuses the registered client.
Credentials belong to another project: Run agentid unlink only when the local binding is stale. Rerun agentid init --force only for an intentional replacement because it leaves the previous remote client registered.
Provider access expired: Run init interactively so the provider CLI can authenticate again. Doctor is deliberately read-only and never opens Clerk, Auth0 or Supabase login.
A local provider block conflicts: The CLI will not overwrite a hand-written or modified Better Auth or Auth.js provider. Keep the manual configuration, or remove the conflicting AgentID block before rerunning.
AgentID returned 429: Wait five minutes before retrying so the per-caller capability window can reset. Repeated starts cannot make an existing approval complete faster.

Run npx @agentmail/agentid-cli@latest doctor for a read-only diagnosis. If the failure remains, email support@agentmail.cc with the CLI version, provider and doctor output. Remove secrets and local paths before sharing logs.

Rerun, unlink or unregister#

Rerunning init is idempotent when the same bound credentials are present. It reapplies and validates managed configuration without registering another client. Use --force only to create an intentional replacement; the previous remote client remains until it is deleted.

agentid unlink: Remove only the three local AgentID variables. The remote client and provider configuration remain.
agentid unregister: Require browser approval, permanently retire the remote OAuth client, then remove the same local variables.

Watch out. Unregistering does not remove the provider configuration, existing application sessions or already-issued AgentID tokens. Issued tokens remain valid until they expire. Remote deletion deliberately has no --yes bypass.