> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vana.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Vana CLI

> Collect your data, run your own Personal Server, and read your data from AI tools, all from the terminal. No desktop app needed.

The Vana CLI puts your data under your control from a terminal. With it you:

* log in with your Vana account
* run your own [Personal Server](/protocol-reference/personal-servers) on your machine, reachable by apps you approve
* collect data from sources such as GitHub, LinkedIn, ChatGPT and Spotify into that server
* read your data from Claude, Claude Code, Cursor and other AI tools over MCP
* give your own agent, such as OpenClaw or Hermes Agent, scoped and paid access that you can revoke

Reading your own data is free. Apps and agents you grant access to pay a small fee per read.

```mermaid theme={null}
flowchart LR
    you["You<br/>vana login"]:::ingress
    ps["Your Personal Server<br/>vana server start"]:::protocol
    src["Sources<br/>vana connect github"]:::neutral
    ai["AI tools<br/>MCP"]:::sdk
    agent["Your agent<br/>OpenClaw, Hermes"]:::sdk

    src -->|"collect"| ps
    you -->|"owns"| ps
    ai -->|"read, with your approval"| ps
    agent -->|"paid read, scoped grant"| ps

    classDef protocol fill:#DCE4FF,stroke:#4141FC,color:#11104a;
    classDef sdk fill:#FFF3D1,stroke:#E6A700,color:#5c4400;
    classDef ingress fill:#E2F4DC,stroke:#34A853,color:#14431f;
    classDef neutral fill:#EEF1F5,stroke:#9AA4B2,color:#1f2937;
```

## Before you start

| You need                    | Why                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| **Node.js 20** or later     | Runs the CLI. The first `vana server start` installs Node 24 for the server if you don't have it |
| A **Vana account**          | You sign in with it at [account.vana.org](https://account.vana.org)                              |
| **macOS, Linux or Windows** | The CLI runs on all three                                                                        |

## Install

```bash theme={null}
npm install -g vana-cli
vana -v
```

<Note>Every command runs on **Vana mainnet** by default. Add `--network moksha` to any command to use the testnet. The two networks don't share servers, data grants or balances. See [Choose your network](/build-a-vana-app/networks).</Note>

## Get started

<Steps>
  <Step title="Log in">
    ```bash theme={null}
    vana login
    ```

    Approve in the browser that opens. The CLI logs in as the account the browser is signed in to on account.vana.org, and prints its address.

    If you don't run a Personal Server yet, the CLI asks: **Start your Personal Server now?** Answer yes and continue with the next step.
  </Step>

  <Step title="Start your Personal Server">
    ```bash theme={null}
    vana server start
    ```

    The first start installs the server once and opens a browser page that asks you to confirm the server is yours. Approve it. The CLI then registers the server for your account, connects it to Vana's relay and prints its public URL:

    ```text theme={null}
    Registered https://0x....server.vana.org.
    Personal Server running at http://localhost:8080
    Reachable by apps at https://0x....server.vana.org
    Running in the background (pid ...). Stop it with `vana server stop`.
    ```

    The first start can take up to a minute. The server keeps running in the background, and your terminal is free again. Later starts take a few seconds and open no browser.

    If you already run the Vana desktop app, the CLI uses the desktop app's server and doesn't start a second one.
  </Step>

  <Step title="Connect a source">
    ```bash theme={null}
    vana sources
    vana connect github
    ```

    `sources` lists everything you can connect. `connect` opens a browser; sign in to the source there. The CLI collects your data and stores it in your Personal Server. Your credentials stay in the browser on your machine.
  </Step>

  <Step title="Look at your data">
    ```bash theme={null}
    vana data show github
    vana server data
    ```

    `data show` prints what was collected. `server data` lists the scopes your Personal Server holds, such as `github.repositories`.
  </Step>
</Steps>

## Read your data from AI tools

Your Personal Server speaks [MCP](/applications/mcp), so AI tools can search and read your data. Reads by you, the owner, are free.

<Tabs>
  <Tab title="Claude Code, Cursor and other local tools">
    Add the CLI as a local MCP server. For Claude Code:

    ```bash theme={null}
    claude mcp add vana -- vana mcp
    ```

    For other tools, add an MCP server with the command `vana mcp`. Then ask, for example, "What are my GitHub repos about?"
  </Tab>

  <Tab title="claude.ai">
    ```bash theme={null}
    vana server status
    ```

    Copy the **MCP URL**, for example `https://0x....server.vana.org/mcp`. In claude.ai, open **Settings → Connectors → Add custom connector**, paste the URL and click **Connect**.

    A Vana page opens on your machine and asks you to approve Claude's access. Untick any scopes you don't want to share, then click **Approve**. The connector then works in claude.ai on the web and on your phone, as long as your server is running.
  </Tab>
</Tabs>

## Where your data lives

```bash theme={null}
vana server status
```

```text theme={null}
  Public URL:    https://0x....server.vana.org (mainnet, reachable)
  MCP URL:       https://0x....server.vana.org/mcp
  Local URL:     http://localhost:8080 (vana server start)
  Data on disk:  ~/.vana/cli/personal-server/mainnet
  Backup:        encrypted in Vana storage, follows your account
```

| Line             | Meaning                                                                                                                     |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Public URL**   | The address apps use to reach your server, through Vana's relay. It answers only while your server runs                     |
| **MCP URL**      | The address to give an AI tool, such as the claude.ai connector                                                             |
| **Local URL**    | The server on your machine, and what runs it: `vana server start` or the Vana desktop app                                   |
| **Data on disk** | Your data, on this machine                                                                                                  |
| **Backup**       | An encrypted copy in Vana storage. Only your account can decrypt it. A server you start on another machine restores from it |

## Manage your server

| Command                          | What it does                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------- |
| `vana server start`              | Starts your server in the background. Does nothing if it's already running                  |
| `vana server stop`               | Stops it. Apps can't reach your data until you start it again                               |
| `vana server start --foreground` | Keeps the server in the terminal with its logs. Stop it with Ctrl+C                         |
| `vana server start --local`      | Runs the server on this machine only, with no public URL. Apps and claude.ai can't reach it |
| `vana server status --all`       | Also lists servers you registered before that no longer answer                              |

The server answers only while your machine is on and the server runs. To collect new data regularly, use `vana schedule add`.

## Give your agent scoped access

Apps and agents don't get your data just because they can reach your server. Each one asks for specific scopes, you approve them in your Vana account, and it pays a fee per read from its own escrow. You can revoke its access at any time.

That is how you hand data to a personal agent without letting it act as you. The CLI gives the agent **its own app identity**, and the agent uses the same `vana` commands as any app.

<Tabs>
  <Tab title="OpenClaw">
    [OpenClaw](https://openclaw.ai) is an open-source personal agent you talk to from chat apps.

    ```bash theme={null}
    npm install -g openclaw@latest
    openclaw onboard --install-daemon
    vana skills install builder
    ```

    `onboard` asks for your model provider key and starts OpenClaw in the background. OpenClaw loads skills from `~/.agents/skills`, where `vana skills install` puts them, so there is nothing more to set up.
  </Tab>

  <Tab title="Hermes Agent">
    [Hermes Agent](https://hermes-agent.nousresearch.com) is an open-source agent by Nous Research, with a terminal UI and sandboxed terminal backends.

    ```bash theme={null}
    curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
    hermes setup
    vana skills install builder
    ```

    `setup` asks for your model provider. Hermes loads skills from `~/.hermes/skills`, so add the shared directory to `~/.hermes/config.yaml`:

    ```yaml theme={null}
    skills:
      external_dirs:
        - ~/.agents/skills
    ```

    Start a new session with `hermes` and check that `hermes skills list` shows `builder`.
  </Tab>
</Tabs>

Then, from the agent:

1. `vana app register --app-url <your agent's homepage>` creates the agent's own key. `vana app whoami` prints its app address.
2. Fund that address in [Vana Account → Developers](https://account.vana.org/developers) with **Fund escrow**. On mainnet you deposit USDC.e.
3. Ask the agent for something that needs your data, for example "Use Vana to read my GitHub repositories and summarize what I worked on this month". It runs `vana app request` and sends you an approval link. Approve only the scopes it needs.
4. The agent reads with `vana app read --pay` and each read settles from its escrow. Your own reads stay free.
5. In the Vana app, **Settings → Access history** lists every read. **Revoke** cuts the agent off on its next read.

The full walkthrough, including running the agent in a sandbox, is in [Give an agent scoped access to your data](/build-a-vana-app/agent-access).

## Use it from an agent or a script

Every command accepts:

| Flag         | Effect                                                         |
| ------------ | -------------------------------------------------------------- |
| `--json`     | Prints machine-readable output                                 |
| `--no-input` | Never prompts. Fails, or prints a URL for you to open, instead |
| `--yes`      | Answers yes to confirmation prompts                            |

The CLI also ships skills that teach a coding agent to use it. Run `vana skills list` to see them and `vana skills install <name>` to install one.

## Troubleshooting

| Symptom                                           | Fix                                                                                                                       |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Logged in as an unexpected address                | Your browser is signed in to another account on account.vana.org. Sign out there, then run `vana logout` and `vana login` |
| `vana server status` says **Public URL: none**    | Your server has no public URL, so apps can't reach it. Run `vana server stop`, then `vana server start` without `--local` |
| `connect` collected data but says **sync failed** | Your server hasn't approved the CLI yet. Run `vana login` again and approve the page it opens                             |
| A `connect` shows no progress for a minute        | Some sources report no progress while they collect. Wait for them to finish                                               |
| Anything else                                     | Run `vana doctor` for a full diagnosis                                                                                    |