vana-com/vana-connect

Connect

Connect personal data from web platforms using the vana CLI and local browser automation.

Setup

Prefer an installed vana CLI on PATH:

command -v vana

If that succeeds, use:

vana

If vana is unavailable, install the current published canary. Prefer:

macOS with Homebrew:

brew tap vana-com/vana
brew install vana

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/vana-com/vana-connect/feat/connect-cli-v1/install/install.sh | sh -s -- --version canary-feat-connect-cli-v1

Only if the installed CLI path is unavailable or blocked, fall back to:

npx -y @opendatalabs/connect@canary

If the user is explicitly testing local changes, fall back to:

node /home/tnunamak/code/vana-connect/dist/cli/bin.js

If neither path is available, follow SETUP.md in this folder.

Before connecting a source, check runtime state with:

vana status --json

If the user needs install, path, or upgrade diagnostics, use:

vana doctor

If the user needs recent setup, fetch, or run logs, use:

vana logs
vana logs <platform>

If the runtime is missing, tell the user: "I need to do a one-time setup first. This downloads a browser engine and some dependencies into ~/.dataconnect/ and usually takes about a minute." Then run:

vana setup --yes

Flow

1. Explore available sources

vana sources --json

This is the source of truth for what the CLI can currently connect. Prefer it over inspecting repo files manually.

If the requested platform is present, use the CLI flow below.

If no connector exists for the platform, tell the user you'll build one — this involves researching the platform's data APIs, writing the extraction code, and testing it. Let them know it'll take a bit and they're welcome to do something else while you work. Then read CREATE.md and follow it.

2. Connect with the CLI

Start with the agent-safe probe:

vana connect <platform> --json --no-input

This will:

• ensure the runtime is installed
• resolve and cache the connector
• try a saved session if one exists
• return structured events and a final outcome such as needs_input, legacy_auth, connected_local_only, or connected_and_ingested

If the outcome is needs_input, rerun interactively:

vana connect <platform>

If the user specifically wants to inspect current state before rerunning, use:

vana status

3. Handle outcomes

The CLI emits structured JSON events in --json mode.

Key outcomes:

• needs_input The connector needs a live login or another manual step. Explain that you'll rerun interactively.
• legacy_auth The connector still depends on showBrowser / promptUser. Explain that this source still needs a headed/manual session path and may not work in fully headless batch mode yet.
• connected_local_only Data was collected locally but no Personal Server target was available.
• connected_and_ingested Data was collected and synced to the Personal Server.

If setup, fetch, or run output is truncated, use:

vana logs
vana logs <platform>

Prefer that over manually hunting through ~/.dataconnect/logs/ or rerunning blindly.

After a successful connect, prefer the CLI data surfaces over raw file inspection when possible:

vana data list
vana data show <platform>
vana data path <platform>
vana logs <platform>

4. Validate, present results, and offer to contribute

If you built or modified a connector, immediately run validation — before presenting results to the user:

node scripts/validate.cjs connectors/<company>/<name>-playwright.js --check-result ~/.dataconnect/last-result.json

Fix any issues the validator reports. The validator checks debug code, login method diversity, schema descriptions, data cleanliness, and more — it is the quality gate. Iterate until validation passes.

Then read the result file and summarize for the user in human terms (see "Communicating with the user" below).

If you built a new connector (not one from the registry), ask the user:

"Want to share this connector so others can connect their [Platform] data too? Contributing means the community helps maintain it when [Platform] changes their site."

If yes, run node scripts/validate.cjs connectors/<company>/<name>-playwright.js --contribute. If no, move on.

5. Suggest what to do with the data

After the contribution question is resolved (or if using an existing connector), suggest use cases from RECIPES.md: user profile generation, personal knowledge base, data backup, cross-platform synthesis, activity analytics.

Communicating with the user

The user can't see what you're doing behind the scenes. Keep them informed at key moments:

1. Before asking for credentials, explain the approach and reassure on privacy:

   • "I'll connect to [Platform] using a local browser on your machine. Your credentials stay local — nothing is sent to any server except [Platform] itself."
   • If using an API key: "This uses [Platform]'s API key. You can find it at [location]. The key stays on your machine."

2. During long operations (building a connector, collecting paginated data), give brief progress updates. Don't go silent for more than ~30 seconds.

3. After collection, summarize results in human terms — not file paths:

   • Good: "Connected! I collected 249 issues, 63 projects, 9 teams, and your profile from Linear."
   • Bad: "Data saved to ~/.dataconnect/last-result.json"
   • Prefer the CLI outcome plus the result file. Build the summary from exportSummary and the scoped keys.

4. On failure, explain what went wrong and what the user can do:

   • Auth failed → "Login didn't work. Can you double-check your credentials?"
   • Platform API changed → "The connector couldn't find the expected data. The platform may have changed their site."

Rules

1. Ask before saving -- no writes to user profile without approval
2. Never log credentials -- no echo, print, or output of secrets
3. One platform at a time
4. Check session first -- try without credentials if a browser profile exists
5. Read connectors before running them
6. Use the CLI as the primary interface -- only drop to raw scripts when debugging or updating connector internals

CLI fallback order

Use this order when choosing the CLI entrypoint:

1. installed vana
2. official installer path for the current canary
3. npx -y @opendatalabs/connect@canary
4. node /home/tnunamak/code/vana-connect/dist/cli/bin.js only for local development or debugging