Authenticating the Agnic Wallet

Check Current Status

npx agnic@latest status --json

If already authenticated, no further action needed. If not, choose the appropriate mode below.

Mode 1: Headless / Token Auth (CI, servers, agents)

Preferred when no browser is available. Generate an API token at app.agnic.ai > Settings > API Tokens.

Option A -- Environment variable (recommended for automation):

export AGNIC_TOKEN=<your-api-token>
npx agnic@latest status --json

The CLI reads AGNIC_TOKEN automatically. All subsequent commands in the same shell session use it without extra flags.

Option B -- Inline flag (one-off commands):

npx agnic@latest --token <your-api-token> status --json

Mode 2: Browser OAuth (interactive terminals)

Use when a browser is available:

npx agnic@latest auth login

This command:

1. Starts a temporary local server on a random port
2. Opens the default browser to the Agnic OAuth consent screen
3. The user signs in (email, Google, or wallet) and approves spending limits
4. The browser redirects back to http://localhost:/callback
5. The CLI exchanges the authorization code for tokens and saves them locally

Wait for the CLI to print Authenticated! before proceeding.

Verify Authentication

npx agnic@latest status --json

Expected output:

{
  "authenticated": true,
  "userId": "did:privy:...",
  "email": "user@example.com",
  "walletAddress": "0x...",
  "tokenExpiry": "2026-05-22T14:30:00Z"
}

Logout

To remove stored credentials:

npx agnic@latest auth logout

Token Storage

• Browser mode: credentials stored in ~/.agnic/config.json with 0600 permissions. Tokens auto-refresh on 401 responses. Refresh token expires after 90 days.
• Token mode: no local storage. The token is read from AGNIC_TOKEN env var or --token flag per invocation.

Error Handling

• "Not authenticated" -- Set AGNIC_TOKEN env var, pass --token, or run auth login
• "Authentication failed" -- User cancelled the browser flow or the 5-min timeout expired
• "Could not open browser" -- The CLI prints a URL to copy and open manually
• "Token expired" -- Browser tokens auto-refresh; API tokens must be regenerated at app.agnic.ai
• "Invalid token" -- Check the token value; it may have been revoked or malformed