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:

• Linux: ~/.lsvault/daemon.log
• macOS: ~/Library/Logs/lsvault-daemon.log
• Windows: %APPDATA%\lsvault\daemon.log

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

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

Daemon Behavior

The daemon watches all configured sync folders and:

1. Detects file changes (create, modify, delete)
2. Waits for a 2-second 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:

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

[Service]
ExecStart=/usr/bin/lsvault sync daemon start
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:

# 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>/usr/local/bin/lsvault</string>
    <string>sync</string>
    <string>daemon</string>
    <string>start</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.log'

Troubleshooting

Daemon Won't Start

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

# Kill stale process
pkill -f "lsvault sync daemon"

# Remove PID file if stuck
rm ~/.lsvault/daemon.pid

# Restart
lsvault sync daemon start

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.log