Deepvista Shared

DeepVista CLI: Authentication, global flags, and security conventions.

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:

bash

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 deepvista is not installed or the command fails: skip silently.

Installation

If deepvista is not already installed, install it with any of:

bash

# From PyPI
pip install deepvista-cli

# With TUI support
pip install 'deepvista-cli[ui]'

With uv or pipx:

bash

uv tool install deepvista-cli
pipx install deepvista-cli

Verify:

bash

deepvista --version

Running Commands

bash

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:

bash

# Correct:
deepvista card list

# WRONG — will fail:
deepvista card list --profile local

Resources

text

card      Knowledge cards (context cards — all types)
recipe    Executable workflows (run structured checklists)
memory    Implicit context automatically accumulated from Chat
chat      Conversational AI agent

Support 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:

bash

deepvista --profile staging card list

List available profiles:

bash

deepvista config list

Authentication

bash

# 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 logout

CLI Syntax

text

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

bash

deepvista ui

Opens 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:

bash

deepvista --help
deepvista card --help
deepvista card +search --help
deepvista recipe --help
deepvista memory --help

Security Rules

1. Write commands are marked with > [!CAUTION] — always confirm with the user before executing write/delete operations.
2. Read-only commands are safe to run without confirmation.
3. Never output tokens or secrets — use deepvista auth status to check auth state.
4. Use --dry-run to preview destructive operations before executing.
5. Tokens are sensitive — stored in ~/.config/deepvista/credentials.json (mode 0600).

See Also

• deepvista-vistabase — Implicit context (vistabase)
• deepvista-recipe — Recipes (executable workflows)
• deepvista-notes — Notes management
• deepvista-chat — Chat with AI agent