DeepVista CLI — Shared Reference
This skill documents authentication, global flags, and security conventions for all DeepVista CLI commands.
On Load
When this skill is loaded, silently run the following command in the background to check for skill updates:
deepvista skill check-update- If the command exits 0: skills are up to date — say nothing, continue normally.
- If the command exits 1 (updates available): inform the user that newer versions of the DeepVista skills are available and show the update command printed by the tool.
- If
deepvistais not installed or the command fails: skip silently.
Installation
If deepvista is not already installed, install it with any of:
# From PyPI
pip install deepvista-cli
# With TUI support
pip install 'deepvista-cli[ui]'With uv or pipx:
uv tool install deepvista-cli
pipx install deepvista-cliVerify:
deepvista --versionRunning Commands
deepvista [GLOBAL FLAGS] <resource> <command> [options]If running from the cloned repo without installing, prefix commands with uv run.
IMPORTANT: Global flags like --profile must come BEFORE the resource name:
# Correct:
deepvista card list
# WRONG — will fail:
deepvista card list --profile localResources
card Knowledge cards (context cards — all types)
recipe Executable workflows (run structured checklists)
memory Implicit context automatically accumulated from Chat
chat Conversational AI agentSupport commands: auth, config, notes (shorthand for card --type note)
Profiles
Commands use the default profile unless you specify one. To target a specific backend, pass --profile NAME before the resource name:
deepvista --profile staging card listList available profiles:
deepvista config listAuthentication
# Interactive: opens browser, authenticates automatically
deepvista auth login
# Non-interactive: visit /cli in browser, paste the code shown
deepvista auth login --code XXXX-XXXX
# Check auth state
deepvista auth status
# Logout
deepvista auth logoutCLI Syntax
deepvista [--profile NAME] <resource> <command> [options]
deepvista [--profile NAME] <resource> +<helper> [args] [options]Global Flags
Global flags go BEFORE the resource name.
| Flag | Default | Description | |
|---|---|---|---|
--profile NAME | default | Config profile to use (e.g. local, staging). | |
| `--format json\ | table` | json | Output format. JSON is default (agent-friendly). |
--verbose | off | Show HTTP request/response details on stderr. | |
--dry-run | off | Show what would be sent without executing. | |
--api-url URL | — | Override backend URL. | |
--version | — | Show version and exit. | |
--help | — | Show help for any command. |
Launch the TUI
deepvista uiOpens the terminal UI with Chat, Notes, Recipes, and Memory panels. Requires: pip install 'deepvista-cli[ui]'
Output Format
- JSON (default): Structured JSON to stdout. Agents should parse this.
- Table: Human-readable table on stderr + JSON on stdout.
- Errors:
{"error": {"code": N, "message": "...", "detail": "..."}}on stderr. - Streaming (chat +send, recipe run): NDJSON — one JSON object per line.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | API error (backend returned error) |
| 2 | Auth error (not logged in / token expired) |
| 3 | Validation error (bad arguments) |
| 4 | Network error (cannot reach backend) |
| 5 | Internal error |
Self-Discovery
Every command supports --help:
deepvista --help
deepvista card --help
deepvista card +search --help
deepvista recipe --help
deepvista memory --helpSecurity Rules
- Write commands are marked with
> [!CAUTION]— always confirm with the user before executing write/delete operations. - Read-only commands are safe to run without confirmation.
- Never output tokens or secrets — use
deepvista auth statusto check auth state. - Use
--dry-runto preview destructive operations before executing. - Tokens are sensitive — stored in
~/.config/deepvista/credentials.json(mode 0600).
See Also
- deepvista-memory — Knowledge cards
- deepvista-recipe — Recipes (executable workflows)
- deepvista-notes — Notes management
- deepvista-chat — Chat with AI agent