# Help Center

Use this page to diagnose common TokST setup and daily-use issues. Each section includes the fastest recovery path and a command to verify the result.

## Installation and updates

### `tokst: command not found`

Install the standalone CLI, then open a new terminal so the updated PATH is loaded.

```sh
curl -fsSL https://tokst.com/install.sh | bash
tokst version
```

Windows PowerShell uses:

```powershell
irm https://tokst.com/install.ps1 | iex
tokst version
```

Windows Git Bash supports the Unix command and opens the PowerShell installer automatically.

### The installed version looks older after an update

`tokst update` upgrades the channel that launched the command: standalone uses the verified binary release, npm runs its global npm update, and Bun runs its global Bun update. Inspect the active channel and repair shell priority when a standalone binary should lead PATH.

```sh
tokst update
tokst version --verbose
tokst doctor
tokst doctor --fix-path
```

Open a new terminal after a standalone installation or PATH repair. The installer keeps npm and Bun installations intact, records its own binary location, and retains cloud authorization.

## Sign in and cloud connection

### Browser authorization does not return to the terminal

Keep the terminal process open while confirming the browser page. Start a fresh flow when the browser says the connection request is unavailable.

```sh
tokst setup
tokst connection test
```

Use an API key for CI, servers, and other unattended environments:

```sh
tokst login --key tk_live_xxxx
tokst connection test
```

### `tokst doctor` shows an Atlas as optional

An Atlas binding only supplies project-directory routing. Your account, workspaces, search, and memories remain available without one. Bind an Atlas when a directory permanently belongs to a project.

```sh
tokst atlas list
tokst atlas bind --atlas-id <atlas-id>
```

## Local mode and SQLite

### Create private memory on this device

```sh
tokst setup --local
tokst local remember "Private note" --type note
tokst local search "Private"
```

Local memory, attachments, search index, and backups stay in the platform application-data directory. See [TokST Local](/docs/local) for backup and explicit cloud sync.

### `CHECK constraint failed` or `SQL logic error`

Update to the latest standalone CLI, create a backup, then inspect the local profile.

```sh
tokst update
tokst local backup create --name before-repair
tokst local status --json
```

Include the full error, `tokst version`, and `tokst local status --json` when reporting a reproducible issue. Keep the generated backup until the write succeeds.

## Workspaces and Atlases

### I cannot create a workspace or Atlas

Workspace and Atlas creation follow the current plan limits. Review account usage in the dashboard, switch to the intended workspace, and retry.

```sh
tokst status
tokst workspace list
tokst atlas list
```

Cloud Free includes one personal workspace and one Atlas. Team workspaces use their own Team subscription and shared quota. See [Product Editions](/docs/editions).

### I cannot see a team invitation

The invitee can review every pending invitation and accept or decline it from the dashboard or CLI.

```sh
tokst workspace inbox
tokst workspace respond <invitation-id> --accept
```

Team owners and admins manage invitations in [Team Collaboration](/docs/team-collaboration).

## MCP and Agent setup

### WorkBuddy, ZCode, Qoder, or Kimi cannot open browser authorization

Create a dedicated API key in Dashboard → API Keys. Configure the client as Streamable HTTP and send the key in every request through the Authorization header. Revoke the key when the client is no longer used.

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp",
      "headers": {
        "Authorization": "Bearer tk_live_your_api_key"
      }
    }
  }
}
```

### MCP tools do not appear

Complete authorization on the same machine that runs the local MCP process, then restart the MCP client.

```sh
tokst connection test
tokst init --agents codex,claude,cursor,opencode,pi --force
```

For remote MCP, reconnect the client to `https://api.tokst.com/mcp` and complete its OAuth approval. See [MCP Overview](/docs/mcp).

### Agent messages are missing

Each Agent reads its own persistent inbox. Start the listener beside a long-running Agent for immediate delivery, and use the inbox to synchronize messages after restarts.

```sh
TOKST_AGENT=1 tokst agent listen --json
TOKST_AGENT=1 tokst message inbox --json
```

Review the active Agent identity with `tokst agent list`. See [Agent Identity](/docs/agent-identity) for permissions, messages, and status.

## Files, usage, and security

### A file is visible but its memory is gone

Open **Files** in the dashboard and review the recycle bin. Restoring the memory restores the normal association; the repair tools identify orphaned attachments for review.

### Upload, usage, or permission requests fail

Confirm the target workspace, available shared or personal quota, and your workspace role. Owners manage billing and audit access; admins manage team content; members manage their own memories.

```sh
tokst status
tokst workspace list
```

API keys inherit the permissions of their owner. Revoke unused keys from the dashboard and create keys only for trusted automation. See [API Keys](/docs/api-keys).

## Still need help?

Gather the command, complete error message, installed version, operating system, and whether the flow used Local, CLI, local MCP, remote MCP, dashboard, or REST API. This makes support and issue triage reproducible.

Useful checks:

```sh
tokst version
tokst doctor
tokst connection test
tokst status --json
```