.suzi Directory

The ~/.suzi/ directory is the Suzi CLI's local data store. It's created automatically the first time you run suzi login and contains authentication tokens, configuration, caches, and session history.

~/.suzi/
├── config.json          # Auth tokens, user info, account selection, preferences
├── sessions.json        # AI coding session history and deployment records
├── history.json         # Sanitized CLI command history
├── actions-cache.json   # Cached protocol actions with JSON schemas
└── skills-cache.json    # Cached skills manifest from registry

config.json

Primary configuration file. Stores authentication credentials, service URLs, account data, and user preferences.

{
  "apiUrl": "https://api-3ihwe.ondigitalocean.app",
  "webUrl": "https://new.suzi.trade",
  "defaultAi": "claude",
  "accessToken": "<JWT>",
  "refreshToken": "<JWT>",
  "user": {
    "id": "uuid",
    "email": "you@example.com",
    "privyUserId": "privy:xxx"
  },
  "activeAccountId": "uuid",
  "accounts": [
    {
      "id": "uuid",
      "name": "My Account",
      "svmWalletAddress": "So1...",
      "evmWalletAddress": "0x..."
    }
  ],
  "preferences": {
    "username": "alice",
    "toolingOnboarding": {
      "codexInstallSkippedAt": "2026-03-01T00:00:00Z",
      "claudeCodexMcpConfiguredAt": "2026-03-01T00:00:00Z",
      "neverRemindCodex": false
    }
  }
}

Field reference

Field	Description
`apiUrl`	API server URL. Defaults to the production endpoint; override with `suzi preferences`.
`webUrl`	Web dashboard URL. Stale URLs (e.g. `v2.suzi.trade`) are auto-migrated on read.
`defaultAi`	Preferred AI provider — `claude` or `codex`. Set via `suzi preferences`.
`accessToken`	JWT used for authenticated API requests. Auto-refreshed when expired.
`refreshToken`	Used to obtain a new `accessToken` without re-authenticating.
`user`	Your user identity: internal ID, email, and Privy authentication ID.
`activeAccountId`	The account currently selected for operations. Switch with `suzi accounts`.
`accounts`	All accounts you have access to, each with Solana and EVM wallet addresses.
`preferences`	Display name, tooling onboarding state (tracks which setup prompts you've completed or skipped).

What writes to it

suzi login — stores tokens, user info, and accounts after OAuth
suzi accounts — updates activeAccountId
suzi preferences — updates apiUrl, webUrl, defaultAi, username
Token refresh — silently updates accessToken and refreshToken on expiry

sessions.json

Tracks AI coding sessions started with suzi start and any agents deployed during those sessions.

{
  "version": "1.0.0",
  "sessions": [
    {
      "sessionId": "abc-123",
      "createdAt": "2026-03-23T10:00:00Z",
      "projectPath": "/Users/you/my-agent",
      "projectName": "my-agent",
      "aiProvider": "claude",
      "model": "claude-opus-4-6",
      "deployments": [
        {
          "agentId": "uuid",
          "deployedAt": "2026-03-23T10:05:00Z",
          "title": "Market Watcher"
        }
      ]
    }
  ]
}

Retention

Maximum 200 sessions are retained.
Sessions older than 90 days are eligible for cleanup.
When the limit is exceeded, the oldest sessions are trimmed automatically.

history.json

A sanitized log of CLI commands you've run, including execution status and duration. Used by suzi feedback to automatically include recent context when reporting issues.

[
  {
    "command": "agents create",
    "args": ["--name", "My Agent"],
    "status": "success",
    "durationMs": 1240,
    "timestamp": "2026-03-23T10:00:00Z"
  },
  {
    "command": "login",
    "args": [],
    "status": "error",
    "durationMs": 3500,
    "errorOutput": "Network timeout after 3000ms",
    "timestamp": "2026-03-23T09:55:00Z"
  }
]

Sanitization

Arguments containing sensitive keywords (token, key, secret, password, auth, credentials, private) are automatically redacted. JWT tokens are replaced with <TOKEN>.

Retention

Maximum 100 entries. Oldest entries are removed when the limit is exceeded.
Error messages are truncated to 500 characters.

actions-cache.json

Locally cached list of all available protocol actions and their JSON schemas. This avoids a network call on every command that needs to look up an action.

{
  "fetchedAt": 1711180800000,
  "actions": [
    {
      "name": "place_order",
      "protocol": "polymarket",
      "description": "Place an order on a Polymarket market",
      "requires": { "wallet": ["evm"] },
      "parameters": { "...JSON Schema..." },
      "response": { "...JSON Schema..." }
    }
  ]
}

Cache behavior

TTL: 60 minutes. After expiry, the next command that needs actions will re-fetch from the API.
Force refresh: Run suzi list-actions reload to bypass the cache and pull fresh data.
Failure handling: Cache write failures are silently ignored — a missing or corrupt cache file simply triggers a fresh fetch.

When to clear

Delete this file (or run suzi list-actions reload) if:

You see stale or missing actions after a platform update
A new protocol was added and actions aren't showing up
Action parameter schemas seem outdated

skills-cache.json

Cached skills manifest downloaded from the Suzi registry. Skills are embedded content bundles (typically markdown and code) used for local AI assistant integrations.

{
  "fetchedAt": 1711180800000,
  "contentHash": "a1b2c3d4",
  "skills": [
    {
      "name": "long-running-agents",
      "description": "Guide for building robust, long-running agents",
      "files": [
        {
          "path": "guide.md",
          "content": "..."
        }
      ]
    }
  ]
}

Cache behavior

TTL: 60 minutes, same as actions cache.
Content hash: A checksum of skill content, used to detect changes.
Force refresh: Run suzi skills sync to bypass the cache and pull the latest skills.

When to clear

Delete this file (or run suzi skills sync) if:

Skills appear outdated or incomplete
You've been told new skills are available but don't see them
Skill installation fails with unexpected content

Troubleshooting

Reset authentication

If you're getting auth errors or need to switch users:

# Option 1: Log out cleanly (clears tokens, user, and account data)
suzi logout

# Option 2: Manually remove tokens from config.json
# Edit ~/.suzi/config.json and delete accessToken and refreshToken fields

Clear caches

# Refresh actions cache
suzi list-actions reload

# Refresh skills cache
suzi skills sync

# Or delete cache files directly
rm ~/.suzi/actions-cache.json
rm ~/.suzi/skills-cache.json

What's safe to delete

File	Safe to delete?	Effect
`actions-cache.json`	Yes	Re-fetched automatically on next use
`skills-cache.json`	Yes	Re-fetched automatically on next use
`history.json`	Yes	Loses command history; `suzi feedback` context will be empty
`sessions.json`	Yes	Loses session/deployment audit trail
`config.json`	Requires re-auth	You'll need to run `suzi login` again

Nuclear reset

To completely reset the CLI to a fresh state:

rm -rf ~/.suzi
suzi login

This removes all local data and requires you to re-authenticate. Caches will rebuild on first use.

On this page