Getting Started

The Lifestream Vault CLI (lsvault) provides a powerful command-line interface for managing vaults, documents, and all SaaS features.

Installation

Install globally via npm:

npm install -g @lifestreamdynamics/vault-cli

OS Keychain Support (Optional)

For secure credential storage via OS keychain on Linux:

sudo apt install libsecret-1-dev

On macOS and Windows, keychain support is built-in.

Authentication

API Key Authentication (Recommended)

Login with an API key:

lsvault auth login --api-key lsv_k_your_api_key_here

Set the API URL if using a custom instance:

lsvault auth login --api-key lsv_k_abc123 --api-url https://api.example.com

Email/Password Authentication

Login with email and password for JWT-based auth:

lsvault auth login --email user@example.com
# Password will be prompted interactively

Check your authentication status:

lsvault auth whoami

Configuration

Configuration Sources (Precedence Order)

The CLI loads configuration from multiple sources in this order:

1. Environment variables: LSVAULT_API_URL and LSVAULT_API_KEY
2. OS Keychain (if keytar available): Secure credential storage
3. Encrypted config: ~/.lsvault/credentials.enc (AES-256-GCM)
4. Plaintext config (deprecated): ~/.lsvault/config.json

Default Values

• API URL: http://localhost:4660 (development)
• Output format: text (when stdout is a TTY), json otherwise

Managing Configuration

View current configuration:

lsvault auth status

Migrate plaintext credentials to secure storage:

lsvault auth migrate

Clear all stored credentials:

lsvault auth logout

Global Flags

All commands support these global flags:

Output Format Examples

Text output (default for terminals):

lsvault vaults list

JSON output (pipe to jq):

lsvault vaults list --output json | jq '.[] | .name'

Table output:

lsvault docs list <vaultId> --output table

Quick Start Example

# 1. Login
lsvault auth login --api-key lsv_k_abc123

# 2. Create a vault
lsvault vaults create "My Notes"

# 3. List vaults to get the vault ID
lsvault vaults list --output json

# 4. Create a document
echo "# Hello World" | lsvault docs put <vaultId> notes/hello.md

# 5. Read it back
lsvault docs get <vaultId> notes/hello.md

# 6. Search across all vaults
lsvault search "hello"

Next Steps

• Explore command groups for detailed command reference
• Check out Common Workflows for practical examples
• Learn about Scripting & Piping for automation

Common Workflows

Backup All Documents from a Vault

#!/bin/bash
# Backup script for a vault

VAULT_ID="abc123"
BACKUP_DIR="./backup-$(date +%Y%m%d)"

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Get list of documents and download each
lsvault docs list $VAULT_ID --output json | jq -r '.[] | .path' | while read path; do
  echo "Backing up: $path"
  mkdir -p "$BACKUP_DIR/$(dirname "$path")"
  lsvault docs get $VAULT_ID "$path" > "$BACKUP_DIR/$path"
done

echo "Backup complete: $BACKUP_DIR"

Bulk Upload Markdown Files

#!/bin/bash
# Upload all markdown files from a directory

VAULT_ID="abc123"
SOURCE_DIR="./local-docs"

find "$SOURCE_DIR" -name "*.md" -type f | while read file; do
  # Calculate relative path
  rel_path="${file#$SOURCE_DIR/}"
  echo "Uploading: $rel_path"
  cat "$file" | lsvault docs put $VAULT_ID "$rel_path"
done

Mirror a Vault to Another

#!/bin/bash
# Copy all documents from one vault to another

SOURCE_VAULT="abc123"
DEST_VAULT="xyz789"

lsvault docs list $SOURCE_VAULT --output json | jq -r '.[] | .path' | while read path; do
  echo "Copying: $path"
  lsvault docs get $SOURCE_VAULT "$path" | lsvault docs put $DEST_VAULT "$path"
done

Search and Export Results

# Search and save matching documents
VAULT_ID="abc123"
QUERY="important & meeting"

# Get search results
lsvault search "$QUERY" --vault $VAULT_ID --output json > search-results.json

# Download all matching documents
cat search-results.json | jq -r '.[] | .path' | while read path; do
  echo "Downloading: $path"
  lsvault docs get $VAULT_ID "$path" > "export/${path}"
done

Convert and Upload Documents

# Convert Word documents to Markdown and upload
VAULT_ID="abc123"

find ./docs -name "*.docx" | while read file; do
  basename="${file%.docx}"
  md_path="${basename#./docs/}.md"

  echo "Converting: $file -> $md_path"
  pandoc "$file" -t markdown | lsvault docs put $VAULT_ID "$md_path"
done

Automated Daily Backup with Cron

Add to crontab (crontab -e):

# Daily backup at 2 AM
0 2 * * * /home/user/scripts/vault-backup.sh >> /var/log/vault-backup.log 2>&1

Backup script (vault-backup.sh):

#!/bin/bash
set -e

VAULT_ID="abc123"
BACKUP_ROOT="/backups/vault"
DATE=$(date +%Y%m%d)
BACKUP_DIR="$BACKUP_ROOT/$DATE"

mkdir -p "$BACKUP_DIR"

# Backup all documents
lsvault docs list $VAULT_ID --output json | jq -r '.[] | .path' | while read path; do
  mkdir -p "$BACKUP_DIR/$(dirname "$path")"
  lsvault docs get $VAULT_ID "$path" > "$BACKUP_DIR/$path"
done

# Create tarball
tar -czf "$BACKUP_ROOT/vault-$DATE.tar.gz" -C "$BACKUP_ROOT" "$DATE"

# Remove directory (keep tarball)
rm -rf "$BACKUP_DIR"

# Keep only last 30 days
find "$BACKUP_ROOT" -name "vault-*.tar.gz" -mtime +30 -delete

echo "Backup complete: vault-$DATE.tar.gz"

Batch Create Share Links

# Create share links for multiple documents
VAULT_ID="abc123"

# Documents to share
DOCS=("blog/post1.md" "blog/post2.md" "blog/post3.md")

for doc in "${DOCS[@]}"; do
  echo "Creating share link for: $doc"
  lsvault shares create $VAULT_ID "$doc" --expires "2024-12-31" --output json | \
    jq -r '"Share link: " + .url'
done

Monitor Webhook Deliveries

#!/bin/bash
# Check webhook delivery status

VAULT_ID="abc123"
WEBHOOK_ID="webhook_xyz789"

while true; do
  clear
  echo "Webhook Deliveries (refreshing every 30s)"
  echo "=========================================="
  lsvault webhooks deliveries $VAULT_ID $WEBHOOK_ID --output table
  sleep 30
done

Scripting & Piping

Piping Basics

The CLI is designed for Unix-style piping. Most commands that output content (like docs get) write to stdout, while status messages go to stderr.

Document Content Flow

# Pipe document between vaults
lsvault docs get vault1 "notes.md" | lsvault docs put vault2 "copied-notes.md"

# Pipe to/from local files
cat local-file.md | lsvault docs put abc123 "uploaded.md"
lsvault docs get abc123 "downloaded.md" > local-copy.md

# Process with standard tools
lsvault docs get abc123 "notes.md" | wc -w  # Word count
lsvault docs get abc123 "notes.md" | grep "TODO"  # Search content

JSON Processing with jq

# Extract specific fields
lsvault vaults list --output json | jq '.[] | .name'

# Filter results
lsvault docs list abc123 --output json | jq '.[] | select(.tags | contains(["important"]))'

# Complex transformations
lsvault search "meeting" --output json | \
  jq 'group_by(.vaultId) | map({vault: .[0].vaultId, count: length})'

Error Handling in Scripts

#!/bin/bash
set -e  # Exit on error
set -o pipefail  # Catch errors in pipes

VAULT_ID="abc123"

# Check if document exists before processing
if lsvault docs get $VAULT_ID "notes.md" --meta &>/dev/null; then
  echo "Document exists, proceeding..."
else
  echo "Error: Document not found" >&2
  exit 1
fi

# Capture output and exit code
if content=$(lsvault docs get $VAULT_ID "notes.md" 2>&1); then
  echo "Success: $content"
else
  echo "Failed to fetch document" >&2
  exit 1
fi

Batch Operations with Parallel Processing

#!/bin/bash
# Upload multiple files in parallel

VAULT_ID="abc123"

# Export function for parallel execution
upload_file() {
  local file="$1"
  local vault_id="$2"
  local rel_path="${file#./docs/}"

  echo "Uploading: $rel_path"
  cat "$file" | lsvault docs put "$vault_id" "$rel_path"
}

export -f upload_file

# Upload up to 4 files in parallel
find ./docs -name "*.md" | \
  parallel -j 4 upload_file {} $VAULT_ID

Conditional Logic Based on Output

#!/bin/bash
# Check subscription tier and act accordingly

tier=$(lsvault user me --output json | jq -r '.subscriptionTier')

if [ "$tier" = "pro" ] || [ "$tier" = "business" ]; then
  echo "Creating share link (available on $tier plan)..."
  lsvault shares create abc123 "notes.md"
else
  echo "Share links require Pro or Business plan"
fi

Output Formatting in Scripts

# Always use --output json for machine parsing
VAULT_COUNT=$(lsvault vaults list --output json | jq 'length')
echo "You have $VAULT_COUNT vaults"

# Use --no-color for log files
lsvault docs list abc123 --no-color --output table > report.txt

# Combine verbose mode with log redirection
lsvault docs put abc123 "test.md" --verbose 2> debug.log

Credential Management in CI/CD

#!/bin/bash
# CI/CD script using environment variables

# Set credentials via environment (no interactive login needed)
export LSVAULT_API_URL="https://vault.lifestreamdynamics.com"
export LSVAULT_API_KEY="lsv_k_ci_key_here"

# Verify connection
if ! lsvault auth whoami --output json &>/dev/null; then
  echo "Authentication failed" >&2
  exit 1
fi

# Run operations
lsvault docs list abc123 --output json > docs-list.json

Advanced: Sync Script with Conflict Detection

#!/bin/bash
# Sync local files to vault with conflict detection

VAULT_ID="abc123"
LOCAL_DIR="./docs"

sync_file() {
  local file="$1"
  local vault_id="$2"
  local rel_path="${file#$LOCAL_DIR/}"

  # Get local file hash
  local_hash=$(sha256sum "$file" | cut -d' ' -f1)

  # Get remote document hash (if exists)
  remote_hash=$(lsvault docs get "$vault_id" "$rel_path" --meta --output json 2>/dev/null | \
    jq -r '.contentHash // empty')

  if [ -z "$remote_hash" ]; then
    echo "New file: $rel_path"
    cat "$file" | lsvault docs put "$vault_id" "$rel_path"
  elif [ "$local_hash" != "$remote_hash" ]; then
    echo "Modified file: $rel_path"
    cat "$file" | lsvault docs put "$vault_id" "$rel_path"
  else
    echo "Unchanged: $rel_path"
  fi
}

export -f sync_file

find "$LOCAL_DIR" -name "*.md" -type f | \
  parallel -j 2 sync_file {} $VAULT_ID

Output Formats

The CLI supports three output formats optimized for different use cases.

Text Format (Default)

Human-readable output with colors and formatting.

lsvault vaults list
# Output:
# My Notes (my-notes) [encrypted] -- Personal notes
# Work Journal (work-journal) -- Daily work log

Features:

• Colored output when stdout is a TTY
• Emoji and symbols for status indicators
• Optimized for readability
• Automatic color detection (--no-color to disable)

JSON Format

Machine-readable structured data.

lsvault vaults list --output json
# Output:
# [
#   {
#     "id": "abc123",
#     "name": "My Notes",
#     "slug": "my-notes",
#     "encrypted": true,
#     "description": "Personal notes",
#     "createdAt": "2024-01-01T00:00:00.000Z"
#   }
# ]

Use cases:

• Piping to jq for filtering/transformation
• Parsing in scripts
• Integration with other tools
• CI/CD pipelines

Best practices:

# Extract specific fields
lsvault vaults list --output json | jq -r '.[] | .name'

# Filter and count
lsvault docs list abc123 --output json | jq 'length'

# Complex queries
lsvault search "meeting" --output json | \
  jq '.[] | select(.tags | contains(["important"]))| .path'

Table Format

Structured tabular output.

lsvault docs list abc123 --output table
# Output:
# +-------------------+-------------+-------+------+
# | Path              | Title       | Tags  | Size |
# +-------------------+-------------+-------+------+
# | notes/hello.md    | Hello World | new   | 1024 |
# | notes/meeting.md  | Meeting     | work  | 2048 |
# +-------------------+-------------+-------+------+

Use cases:

• Reports and dashboards
• Piping to column or csvlook
• Better readability for list commands

Automatic Format Selection

The CLI automatically selects the best format based on context:

• TTY detected: Uses text format with colors
• Pipe/redirect: Uses json format (for better machine parsing)
• Explicit flag: Always honors --output flag

# TTY: colorful text output
lsvault vaults list

# Piped: JSON output (auto-selected)
lsvault vaults list | jq '.[] | .name'

# Force text in pipe
lsvault vaults list --output text | less

Raw Output for Document Content

Document content commands (docs get) output raw content by default:

# Raw markdown (no JSON wrapping)
lsvault docs get abc123 "notes.md"

# Use --meta flag for metadata as JSON
lsvault docs get abc123 "notes.md" --meta --output json

Color Control

# Disable colors (useful for log files)
lsvault vaults list --no-color

# Force colors even when piped
FORCE_COLOR=1 lsvault vaults list

# Environment variable
export LSVAULT_NO_COLOR=1
lsvault vaults list

Daemon Mode

The sync daemon enables automatic background synchronization of local folders with vaults.

Starting the Daemon

# Start daemon in background
lsvault sync daemon start

# Check daemon status
lsvault sync daemon status

# Stop daemon
lsvault sync daemon stop

Daemon Logs

Daemon logs are written to ~/.lsvault/daemon/daemon.log on every platform.

# Follow daemon logs
tail -f ~/.lsvault/daemon/daemon.log

# View recent errors
grep ERROR ~/.lsvault/daemon/daemon.log | tail -20

Daemon Behavior

The daemon watches all configured sync folders and:

1. Detects file changes (create, modify, delete)
2. Waits for the configured debounce period
3. Syncs changes to the vault based on sync mode
4. Resolves conflicts using the configured strategy

Systemd Service (Linux)

Create a systemd user service for automatic startup. The daemon only syncs folders whose configuration has auto-sync enabled, so initialize (or re-initialize) each folder with --auto-sync first — a daemon with no auto-sync folders starts fine but does nothing:

lsvault sync init <vaultId> ~/vault --auto-sync --interval 5m
lsvault sync list   # the Auto column must show "enabled"

# Find the installed executable and use that exact path in ExecStart below
command -v lsvault

# Create service file
cat > ~/.config/systemd/user/lsvault-sync.service <<EOF
[Unit]
Description=Lifestream Vault Sync Daemon
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
ExecStart=/absolute/path/from-command-v sync daemon run
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
EOF

# Enable and start service
systemctl --user enable lsvault-sync
systemctl --user start lsvault-sync

# Check status
systemctl --user status lsvault-sync

launchd Service (macOS)

Create a LaunchAgent for automatic startup:

# Find the installed executable and use that exact path in ProgramArguments below
command -v lsvault

# Create plist file
cat > ~/Library/LaunchAgents/com.lifestream.vault.sync.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.lifestream.vault.sync</string>
  <key>ProgramArguments</key>
  <array>
    <string>/absolute/path/from-command-v</string>
    <string>sync</string>
    <string>daemon</string>
    <string>run</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>
EOF

# Load service
launchctl load ~/Library/LaunchAgents/com.lifestream.vault.sync.plist

# Check status
launchctl list | grep lifestream

Monitoring Daemon Activity

#!/bin/bash
# Monitor daemon activity

watch -n 5 'lsvault sync daemon status && echo "" && tail -10 ~/.lsvault/daemon/daemon.log'

Troubleshooting

Daemon Won't Start

# Always ask the daemon to stop first — this is the clean path and clears
# the PID file itself when the process is still alive
lsvault sync daemon stop

# Check for a leftover daemon process
ps aux | grep "lsvault sync daemon"

# Only if the process is gone but the PID file is stale, remove it by hand
rm ~/.lsvault/daemon/daemon.pid

# Restart
lsvault sync daemon start

Daemon Runs But Nothing Syncs

The daemon only picks up folders initialized with --auto-sync. Check the Auto column in lsvault sync list; if it says "disabled", re-run lsvault sync init ... --auto-sync for that folder.

Sync Not Working

# Check sync configurations
lsvault sync list

# Verify vault access
lsvault vaults get <vaultId>

# Check for conflicts
lsvault sync status <syncId>

# Review logs
tail -50 ~/.lsvault/daemon/daemon.log