CLI: Utilities & Diagnostics

Overview

The Trix CLI includes several utility commands for diagnostics, system health checks, version management, and quick access to documentation. These tools help you troubleshoot issues, keep your CLI up to date, and access help when needed.

doctor

Run comprehensive diagnostics to verify your Trix CLI installation and configuration. This command checks your setup and identifies potential issues.

# Run diagnostics
trix doctor

The doctor command checks:

• CLI Version: Current version and available updates
• Configuration File: Verifies config file exists and is readable
• Authentication: Checks if API key or token is configured
• API Connection: Tests connectivity to Trix API with latency measurement
• Default Space: Verifies default space configuration
• Account & Credits: Displays plan and credit balance
• Shell Completion: Checks if tab completion is installed

Example output:

Trix Doctor
Checking your setup...

  ✓ CLI Version: trix 1.2.3
    Go 1.21.5, linux/amd64 (latest)
  ✓ Config File: Found
    /home/user/.trix/config.yaml
  ✓ Authentication: API key configured
    Source: config file
  ✓ API Connection: Connected (45ms)
    https://api.trixdb.com
  ✓ Default Space: Configured
    space_abc123
  ✓ Account: Pro
    Status: active
  ✓ Credits: 8,500 available
    Used this period: 1,500 / 10,000
  ! Shell Completion: Not installed
    Run 'trix completion --help' for setup instructions

Everything looks good!

version

Display version information for the Trix CLI, including build details and platform.

# Show version information
trix version

# Show just the version number (for scripting)
trix version --short

# Check if a newer version is available
trix version --check

Version output includes:

• CLI version number
• Git commit hash
• Build timestamp
• Go version used to build
• Platform (OS/architecture)
• Available update notification (if newer version exists)

version Options

update

Update the Trix CLI to the latest version. The update process automatically downloads, verifies, and installs the new version.

# Update to latest version
trix update

# Check for updates without installing
trix update --check

# Force update (even if already on latest)
trix update --force

# Skip confirmation prompt
trix update --yes

The update process:

1. Checks GitHub for the latest release
2. Compares with your currently installed version
3. Downloads the appropriate binary for your platform
4. Verifies the download with SHA256 checksum
5. Installs the new version
6. Confirms successful update

update Options

stats

Display statistics about your memory collection, including counts, tag frequencies, and metrics.

# Show overall stats
trix stats

# Show stats for specific space
trix stats --space work

# Show detailed tag breakdown
trix stats --tags

Statistics include:

• Total number of memories
• Number of private memories
• Unique tags count
• Average memory priority
• Number of spaces (if viewing all)
• Tag frequency breakdown (with --tags)

Example output with tag breakdown:

  Memory Statistics

  Total memories: 1,523
  Private memories: 234
  Unique tags: 67
  Avg priority: 5.3
  Spaces: 8

  Tag Breakdown

  work                  342 ████████████████████
  meeting-notes         187 ███████████
  important             142 ████████
  project               98  █████
  personal              76  ████

  ...and 62 more tags

whoami

Display the currently authenticated user and account information.

# Show current user
trix whoami

# Output as JSON
trix whoami -o json

Displays:

• Account name
• Account ID
• API URL being used

open

Open Trix web pages in your default browser for quick access to documentation, dashboard, and settings.

# Open home page
trix open

# Open documentation
trix open docs

# Open API keys management
trix open keys

# Open pricing page
trix open pricing

Available Pages

help

Get help for any command with detailed usage information, options, and examples.

# Show help for main command
trix help

# Show help for a specific command
trix help remember
trix help recall
trix help billing

# Use --help flag (equivalent)
trix remember --help
trix billing credits --help

# List all available commands
trix --help

Configuration Commands

View and manage CLI configuration settings.

# Show all configuration settings
trix config list

# Get a specific setting
trix config get default_space
trix config get output

# Set a configuration value
trix config set output json
trix config set default_space space_abc123

# Show config file location
trix config path

# View default values for new memories
trix config defaults

# Set default tags for all new memories
trix config defaults tags "work,notes"

# Set default expiration
trix config defaults expire 30d

Common configuration options:

• api_url - Trix API endpoint
• default_space - Default space for operations
• output - Default output format (table, json, yaml)
• defaults.tags - Tags to add to all new memories
• defaults.expire - Default expiration for new memories

Shell Completion

Generate shell completion scripts for Bash, Zsh, Fish, and PowerShell to enable tab completion for commands, flags, and dynamic values.

# Add to ~/.bashrc
source <(trix completion bash)

# Or install permanently
trix completion bash > /etc/bash_completion.d/trix

Shell completion provides:

• Command and subcommand completion
• Flag completion (--flag)
• Dynamic suggestions for spaces, memory IDs, and tags
• File path completion where applicable

Proactive Knowledge Management

The CLI includes proactive commands that help you maintain and improve your knowledge base by identifying issues, suggesting improvements, and finding stale content.

trix suggest

Get AI-powered suggestions for improving your knowledge base. The command analyzes your memories and provides actionable recommendations.

# Get suggestions for improving your knowledge base
trix suggest

# JSON output for automation
trix suggest -o json

Suggestions are grouped by priority:

• High Priority - Critical issues requiring immediate attention
• Medium Priority - Important improvements to consider
• Low Priority - Nice-to-have enhancements

Types of suggestions include:

• Topics with sparse coverage (knowledge gaps)
• Areas that need more documentation
• Organizational improvements
• Quality enhancement recommendations

trix contradictions

Find memories that contain potentially conflicting information. This helps maintain consistency in your knowledge base.

# Find contradictions across all memories
trix contradictions

# Limit results
trix contradictions --limit 20

# Focus on specific tags
trix contradictions --tags "api-design"

# Check project-specific contradictions
trix contradictions --tags "deployment"

The command finds:

• Memories with explicit "contradicts" relationships
• Semantically similar memories with different conclusions
• Information that may need reconciliation

trix stale

Identify memories that haven't been accessed recently and may need review or archival. Stale memories can clutter your knowledge base and may contain outdated information.

# Find memories not accessed in 14+ days (default)
trix stale

# Custom threshold (30 days)
trix stale --days 30

# Find very old memories
trix stale --days 90

# Limit results
trix stale --limit 50

Output includes:

• Memory ID and truncated content
• Associated tags
• Days since last access (color-coded by severity)

Proactive Command Flags

Command Reference

Utility Commands

Common Examples

Troubleshooting Setup

# Check if everything is working
trix doctor

# Verify authentication
trix whoami

# Test API connection
trix account info

# Check configuration
trix config list

Update Workflow

# Check current version
trix version

# Check if update available
trix version --check

# Update to latest
trix update

# Verify new version
trix version

Statistics Monitoring

# Overall stats
trix stats

# Stats for specific space
trix stats --space work

# Detailed tag analysis
trix stats --tags

# Export stats for analysis
trix stats -o json > stats-$(date +%Y%m%d).json

Quick Access

# Open documentation
trix open docs

# Manage API keys
trix open keys

# View pricing
trix open pricing

# Get help
trix help remember

Best Practices

Regular Maintenance

• Run trix doctor monthly to check system health
• Keep the CLI updated with trix update
• Enable shell completion for better productivity
• Review trix stats to understand your usage patterns

Troubleshooting Tips

• Always run trix doctor first when encountering issues
• Check trix version to ensure you're on a supported version
• Use -vv flag for debug output on any command
• Verify authentication with trix whoami
• Check API connectivity: trix account info

Productivity

• Install shell completion for faster command entry
• Use trix open docs for quick documentation access
• Set up aliases for frequently used commands
• Use --help to discover command options

Next Steps

• CLI Overview - Main CLI documentation
• Memory Commands - Core memory operations
• Configuration - Detailed configuration guide
• Support - Get help from the Trix team