# Getting Started

Get up and running with TokST in under one minute. This guide walks you through installation, authentication, creating your first atlas, and storing a memory.

## Agent Setup (one link — fastest way)

Copy this message and paste it into your AI agent's chat:

```
Read https://tokst.com/skill.md and install TokST memory skill step by step.
Start with: curl -fsSL https://tokst.com/install.sh | bash

The installer keeps an existing TokST connection during CLI upgrades. Browser approval opens only for a first connection or an expired credential.
```

The agent reads the guide, installs the standalone CLI, then follows the matching Skill and MCP configuration. Browser-capable clients complete OAuth authorization; static MCP clients use a dedicated API key. Works with Claude Code, Cursor, Codex, ZCode, and any MCP-compatible agent.

See the full [Agent Setup guide](/docs/agent-setup) for details.

## One-Click Install

The fastest way to install TokST and all prerequisites:

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

This downloads a checksum-verified standalone TokST CLI, opens browser authorization, and leaves the machine ready for `tokst` commands. macOS and Linux installation requires only a Unix terminal and `curl`; Windows uses PowerShell. Supported targets are macOS Apple Silicon, macOS Intel, Linux x64, Linux ARM64, Windows x64, and Windows ARM64. It does not require Bun, Node.js, npm, or a package manager.

Windows PowerShell:

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

Git Bash on Windows also supports `curl -fsSL https://tokst.com/install.sh | bash`; it detects Windows and hands off to the same PowerShell installer.

Upgrade through the current install channel at any time. Standalone installations download a verified binary; npm and Bun installations update their global package:

```bash
tokst update
tokst version
```

## Browser Authorization

The installer opens TokST in the browser and stores a verified local credential. Verify it at any time:

```bash
tokst doctor
tokst status
```

API keys are intended for CI, servers, and unattended automation. Create and manage them in the [dashboard](https://tokst.com/dashboard/api-keys).

## Connect a Repository and Your Agents

Run this from any directory. TokST writes local instructions for selected agents without overwriting existing files. Atlas creation and directory binding use separate commands.

```bash
tokst init --agents codex,claude,cursor,opencode,pi
tokst doctor
```

Use `tokst init --force` when you intentionally want to refresh generated integration files. `tokst init` works without Git or cloud access. `tokst doctor` checks authentication, optional Git and Atlas binding, and generated agent files.

## Create Your First Atlas

An **Atlas** is a named knowledge base that holds related memories. Create one:

```bash
tokst atlas init --name "MyKnowledge"
tokst atlas bind --atlas-id <id>
```

You can list your atlases to confirm:

```bash
tokst atlas list
```

## Store Your First Memory

Memories are the core unit of information in TokST. Store one:

```bash
tokst remember "Hello TokST!" --type note
```

You can categorize memories by type: `fact`, `decision`, `preference`, `task`, `architecture`, or `note`.

Attach files or images to enrich your memories:

```bash
tokst remember "Meeting notes with diagram" --file diagram.png
```

### Batch Import

Import an entire folder of files as memories — text files are auto-extracted:

```bash
tokst import ./my-docs --dry-run               # preview first
tokst import ./my-docs --type note --tags imported  # import with tags
```

## Search Your Memories

Find memories with keyword or semantic search:

```bash
tokst search "hello"
```

For richer results, use additional filters:

```bash
tokst search "deployment" --type decision --tags production --limit 10
```

## Check Status

View your account and usage details at any time:

```bash
tokst status
```

For machine-readable output (useful for scripting):

```bash
tokst status --json
```

## MCP Server Setup

To connect TokST with AI agents that support the Model Context Protocol (Claude Desktop, Cursor, Codex CLI), add this to your MCP config:

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

The MCP client opens TokST to complete OAuth authorization and needs no local runtime. See the [MCP Server Reference](/docs/mcp) for configuration details for specific clients.

## Download Attachments

If a memory has file attachments, pull them to your local machine:

```bash
tokst memory download mem_xxxxx                    # all attachments → ~/Downloads
tokst memory download mem_xxxxx --out ./files      # specify output directory
tokst memory download mem_xxxxx --json             # machine-readable output
```

## What's Next?

- Browse the [CLI Reference](/docs/cli) for all available commands
- Learn about [Memory Types](/docs/memories) and when to use each one
- Set up [File Attachments](/docs/attachments) to enrich memories with documents
- Organize your knowledge with [Workspaces](/docs/workspaces) and [Atlases](/docs/atlases)
- Give your AI agent persistent memory via [Agent Setup](#agent-setup-one-link--fastest-way)