---
title: CLI Tool
description: Command-line interface for Agnic Wallet operations and x402 transactions
---

# CLI Tool

The `agnic` CLI lets you manage your Agnic Wallet and authorize transactions directly from the terminal. It's designed for AI agents, scripts, and developers who prefer the command line.

---

## Installation

```bash
npx agnic@latest --help
```

Or install globally:

```bash
npm install -g agnic
```

---

## Authentication

The CLI supports three authentication methods (in priority order):

1. **`--token` flag** — passed directly on each command
2. **`AGNIC_TOKEN` env var** — set in your shell environment
3. **Stored token** — saved locally via `agnic auth login`

### Login via Browser (OAuth2)

```bash
agnic auth login
# Opens your browser → sign in → set spending limits → done!
# Output: Authenticated!
# Email: agent@company.com
# Wallet: 0x046906b3...
```

The CLI opens your browser to Agnic where you sign in with your account and set spending limits. Once approved, tokens are saved locally with 90-day expiry. Tokens auto-refresh when expired.

### Using Environment Variable

```bash
export AGNIC_TOKEN=agnic_at_abc123...
agnic balance
```

### Using Token Flag

```bash
agnic balance --token agnic_at_abc123...
```

### Logout

```bash
agnic auth logout
```

---

## Commands

### `agnic status`

Check authentication and wallet status.

```bash
agnic status
# User ID: did:privy:abc123
# Email: agent@company.com
# Wallet: 0x046906b3...
# Token expires: 89 days
```

### `agnic balance`

Check USDC balance across networks.

```bash
# All networks
agnic balance
# Network    Currency   Balance
# base       USDC       $125.50
# solana     USDC       $0.00

# Specific network
agnic balance --network base
# base: $125.50 USDC
```

### `agnic address`

Show your wallet address.

```bash
agnic address
# 0x046906b3cd9d73bf85eb01d795d333b364b75842
```

### `agnic x402 search`

Search for X402-enabled APIs.

```bash
agnic x402 search "sentiment analysis"
# Found 3 API(s):
#   1. Sentiment Pro
#      Real-time sentiment analysis
#      Price: $0.001 /request
```

Options:
- `--category <cat>` — Filter by category (AI, Crypto, Data, Finance, Weather)
- `--limit <n>` — Max results (default: 10)

### `agnic x402 pay`

Make an x402 request to an API.

```bash
agnic x402 pay https://api.example.com/data
# Requesting https://api.example.com/data...
# Request complete!
# Status: 200
# Cost: $0.001
# Response:
# { "result": "..." }
```

Options:
- `--method <METHOD>` — HTTP method (default: GET)
- `--body <json>` — Request body as JSON string

---

## JSON Output

All commands support `--json` for machine-readable output:

```bash
agnic balance --json
```

```json
[
  { "network": "base", "balance": "125.50", "address": "0x046906b3..." },
  { "network": "solana", "balance": "0", "address": "N/A" }
]
```

---

## Configuration

The CLI stores configuration at `~/.agnic/config.json`:

```json
{
  "accessToken": "agnic_at_abc123...",
  "refreshToken": "agnic_rt_xyz789...",
  "expiresAt": 1756000000000,
  "userId": "did:privy:abc123",
  "email": "agent@company.com",
  "walletAddress": "0x..."
}
```

File permissions are set to `0600` (owner-only read/write).

<Callout type="info">
  **Token Auto-Refresh:** When your access token expires, the CLI automatically refreshes it using the stored refresh token. No manual re-authentication needed unless the refresh token also expires (90 days).
</Callout>

### Custom API URL

```bash
agnic --api-url https://custom.api.com balance
```

---

## Agent Identity

Check your agent's on-chain ERC-8004 identity, trust score, and delegation info.

```bash
agnic agent-identity [--json]
```

**Example output:**

```
Agent Identity

  Agent ID:     #396
  Chain ID:     84532
  Wallet:       0xe38b20d6eb4dbd04b7f13fa8f9b6352d3824a0e1
  Trust Score:  26
  Status:       active
  Delegation:   active (ID: 4a4ce438-...)

  Agent Card:   https://kya.agnic.ai/.well-known/agent-cards/396.json
```

---

## Agent Email

Manage your agent's dedicated email address (`agent-{id}@agent.agnic.ai`).

```bash
# Show email address
agnic email address [--json]

# Create email alias
agnic email setup [--display-name <name>] [--json]

# Check inbox
agnic email inbox [--limit <n>] [--json]

# Send email
agnic email send --to <address> --subject <subject> --body <body> [--json]

# Reply to a message
agnic email reply --message-id <id> --body <body> [--json]
```

**Example:**

```bash
agnic email setup --display-name "Research Agent"
agnic email send --to user@example.com --subject "Results" --body "Analysis complete"
agnic email inbox --json
```

---

## Example: Agent Script

```bash
#!/bin/bash
# Automated agent workflow

# Check balance before operations
BALANCE=$(agnic balance --network base --json | jq -r '.[0].balance')
echo "Current balance: $BALANCE USDC"

# Access an x402 API service
agnic x402 pay https://api.example.com/analysis \
  --method POST \
  --body '{"query": "latest market data"}' \
  --json
```

---

## Next Steps

<Cards>
  <Card title="AI Agent Skills" href="/docs/agnicpay-features/skills">
    Use Agnic skills with AI assistants
  </Card>
  <Card title="API Tokens" href="/docs/authentication/api-tokens">
    Generate tokens via the dashboard
  </Card>
</Cards>