vist is a command-line client for Vist. It talks to the same MCP server that Claude Desktop and other AI clients use, so everything you can do there, you can do from a terminal: load your context, search notes, create tasks, record memories.
It's useful in two situations:
- Coding agents. Instead of connecting the MCP server, you give the agent a short skill file (about 1,100 tokens) and it calls
vistlike any other shell command. That keeps its context window smaller. - Scripts. Output is JSON when piped, so it works with
jq, cron jobs and anything else in your shell.
Install
With Homebrew, on macOS or Linux:
brew install davidheijl/tap/vist
Without Homebrew, download the binary for your platform from the releases page (look for the cli-v* tags), put it somewhere on your PATH, and make it executable. Builds exist for macOS and Linux (Intel and ARM) and for Windows. The Windows build hasn't been tested yet.
Check it works:
vist version
Set up with vist init
vist init
This does three things:
- Opens your browser so you can sign in to Vist and approve the CLI.
- Fetches the list of commands from your Vist account.
- Detects which coding agents you have installed and writes a Vist skill for each of them.
Supported agents are Claude Code, OpenCode, Cursor and GitHub Copilot CLI. Some of them read each other's skill folders, so init writes the smallest set of files that gives each agent exactly one copy. For example, if you use Claude Code and OpenCode, one file in .claude/skills/vist/ covers both.
init never overwrites a file that already exists. Useful options:
| Option | What it does |
|---|---|
--global |
Write the skill to your user folder instead of the current project |
--agent <name> |
Write a skill for an agent that isn't installed on this machine |
--print |
Show the skill text without writing anything |
--force |
Replace an existing skill file |
--no-agents |
Only sign in and fetch commands |
After that, start a session with your agent. The skill tells it to run vist load_context first.
If you use Claude Code and already had the Vist MCP connector enabled, you can turn it off. The skill covers the same tools.
Running commands
Every Vist tool is a command, and its arguments are flags. Argument names use dashes, so folder_id becomes --folder-id:
vist load_context
vist list_notes --folder-id 3 --limit 20
vist search_knowledge_base --query "pricing decision"
vist create_task --description "Send the invoice" --due-date 2026-10-01 --priority high
vist record_memory --title "Chose Postgres" --content "..." --memory-type decision_log
To find your way around:
vist tools # every command available on your account
vist schema create_task # the flags for one command
The command list comes from the server and is cached for an hour, so new Vist tools appear without updating the CLI.
Output and exit codes
Data goes to stdout and everything else (progress, warnings, errors) goes to stderr, so piping is always safe.
| Flag | Output |
|---|---|
--json |
JSON (the default when piped) |
--jsonl |
One JSON object per line |
--table |
A table (the default in a terminal) |
-q |
No progress messages |
Exit codes:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | The tool returned an error |
| 2 | Bad arguments. Check vist schema <tool> |
| 3 | Not signed in. Run vist auth login |
| 4 | Still rate limited after retrying |
| 5 | A batch partly failed |
Reading and writing in bulk
--all pages through every result for you:
vist list_notes --all --jsonl | jq -r .title
vist list_notes --all --max-items 500 --jsonl > notes.jsonl
For many writes, put one operation per line in a file:
{"tool": "create_task", "arguments": {"description": "Call the accountant", "priority": "high"}}
{"tool": "create_task", "arguments": {"description": "Renew the domain"}}
Then run it:
vist batch ops.jsonl --dry-run # show what would happen
vist batch ops.jsonl --continue-on-error --report report.json # run it
vist batch --retry-failed report.json # retry only what failed
Every line is checked before anything is sent, so a mistake on line 90 doesn't leave you with 89 changes already made.
Your account allows 100 requests per minute, shared between all your MCP clients and the CLI. The CLI stays under that by default and waits and retries when it hits the limit.
Signing in
vist init handles this, but the commands are also available on their own:
vist auth login # sign in through the browser
vist auth status # who you're signed in as
vist auth logout # sign out and revoke the token
Sign-in uses OAuth, the same way other MCP clients connect. Your token is stored in your system keychain and refreshed automatically.
Using it in CI or on a server
Skip the browser by setting an environment variable:
export VIST_API_KEY=... # an API key from Settings → API
# or
export VIST_TOKEN=... # an OAuth access token
vist auth token prints a current access token if you want to hand one to another process.
Upgrading
brew upgrade vist
vist init --force
The second command refreshes the skill files so your agents get any changes.
Frequently asked questions
Do I need the MCP server connected as well?
No. The CLI talks to the MCP server for you. You can use both, but in a coding agent the skill is enough.
Which plans include the CLI?
All of them.
Does it work on Windows?
There's a Windows build on the releases page, but it hasn't been tested yet. If you try it, let us know how it goes on Discord.
My agent doesn't know about Vist after running init.
Start a new agent session. Skills are loaded when a session starts. If you ran init in one project and opened another, run it again there, or use vist init --global.