Daemon CLI Reference

Complete reference for all trixd commands and flags.

Updated Oct 6, 2026

Command Overview

The trixd CLI provides commands for running, managing, and monitoring the Trix daemon.

Command	Description
`trixd run`	Run daemon in foreground
`trixd install`	Install as system service
`trixd uninstall`	Remove system service
`trixd start`	Start the installed service
`trixd stop`	Stop the running service
`trixd restart`	Restart the service
`trixd status`	Show daemon status
`trixd logs`	View daemon logs
`trixd config`	Manage configuration (get/set/list/validate/path)
`trixd doctor`	Run diagnostic checks
`trixd version`	Show version info

trixd run

Run the daemon in the foreground. Best for development, debugging, and testing configuration changes.

# Run with default config
trixd run

# Run with verbose logging
trixd run -v      # verbose
trixd run -vv     # debug
trixd run -vvv    # trace

# Run with custom config file
trixd run --config /path/to/config.yaml

# Run quietly (errors only)
trixd run -q

Press Ctrl+C to gracefully stop the daemon. It will complete any in-progress operations and persist the cache before exiting.

Use trixd run during development to see real-time output. For production, use trixd install to run as a system service.

Service Commands

trixd install

Install the daemon as a system service. This registers the daemon with your operating system's service manager.

# Install as user service (recommended)
trixd install

# Install with custom config path
trixd install --config /etc/trix/daemon.yaml

On Linux and macOS, you may need elevated permissions for system-wide installation. User-level services are recommended for most use cases.

trixd uninstall

Remove the daemon from the system service manager:

# Stop and uninstall
trixd uninstall

trixd start

Start the installed service:

trixd start

trixd stop

Stop the running service gracefully:

trixd stop

trixd restart

Restart the service (useful after configuration changes):

trixd restart

trixd status

Show detailed daemon status including health, cache stats, and sync info:

trixd status

# Example output:
# +-------------------------------------+
# | Trix Daemon Status                  |
# +-------------------------------------+
# | Status:    running                  |
# | PID:       12345                    |
# | Uptime:    2h 15m 32s              |
# |                                     |
# | API:       connected                |
# | Cache:     1,234 memories           |
# | Last Sync: 15 seconds ago           |
# |                                     |
# | Watchers:  2 directories            |
# | IPC:       active (3 connections)   |
# +-------------------------------------+

JSON Output

# Get status as JSON for scripting
trixd status --json

# Example output:
{
  "status": "running",
  "pid": 12345,
  "uptime_seconds": 8132,
  "api": {
    "connected": true,
    "url": "https://api.trixdb.com"
  },
  "cache": {
    "entries": 1234,
    "size_bytes": 52428800
  },
  "sync": {
    "last_success": "2024-01-15T10:30:00Z",
    "next_scheduled": "2024-01-15T10:30:30Z"
  },
  "watchers": 2,
  "ipc_connections": 3
}

trixd logs

View daemon logs:

# Show last 50 log lines (default)
trixd logs

# Show last N lines
trixd logs -n 100

# Follow logs in real-time (like tail -f)
trixd logs -f

# Combine options
trixd logs -f -n 20

# Filter by level (if using JSON logs)
trixd logs --level error

Flag	Description
`-f, --follow`	Stream logs in real-time
`-n, --lines N`	Show last N lines (default: 50)
`--level LEVEL`	Filter by log level
`--since DURATION`	Show logs since duration (e.g., 1h, 30m)

trixd doctor

Run comprehensive diagnostic checks to identify configuration and connectivity issues:

trixd doctor

# Example output:
# Trix Daemon Diagnostics
# ----------------------
# Configuration file found
# Configuration valid
# Cache directory accessible
# Log directory writable
# API connection successful
# Authentication valid
# IPC socket path available
#
# All checks passed!

Diagnostic Checks

Configuration - Validates config file syntax and required fields
Directories - Checks read/write access to cache and log directories
API Connection - Tests connectivity to the Trix API
Authentication - Verifies API key or token is valid
IPC Socket - Checks socket path is available
Service Status - Reports if daemon is installed/running

Run trixd doctor first when troubleshooting issues. Include the output when seeking support.

trixd version

Show version and build information:

trixd version

# Example output:
# trixd v1.2.0
# Commit: abc123def
# Built:  2024-01-15T10:30:00Z
# Go:     go1.21.5
# OS:     linux/amd64

# Check for updates
trixd version --check

# JSON output
trixd version --json

Global Flags

These flags are available for all commands:

Flag	Description
`--config PATH`	Path to config file (default: ~/.trix/daemon.yaml)
`-v, --verbose`	Increase verbosity (-v, -vv, -vvv)
`-q, --quiet`	Suppress non-error output
`--json`	Output in JSON format (where supported)
`--help`	Show help for any command

Verbosity Levels

# Normal output
trixd status

# Verbose - includes additional info
trixd status -v

# Debug - includes debug messages
trixd status -vv

# Trace - maximum detail (noisy)
trixd status -vvv

Common Examples

Development Workflow

# Start daemon in foreground with debug logging
trixd run -vv

# In another terminal, check status
trixd status

# View logs
trixd logs -f

Production Setup

# Verify configuration
trixd doctor

# Install as service
trixd install

# Start and verify
trixd start
trixd status

Troubleshooting

# Run diagnostics
trixd doctor

# Check current status
trixd status

# View recent errors
trixd logs -n 100 --level error

# Stop service and run in foreground for debugging
trixd stop
trixd run -vvv

Scripting

#!/bin/bash

# Check if daemon is running
if trixd status --json | jq -e '.status == "running"' > /dev/null; then
    echo "Daemon is running"
    CACHE_COUNT=$(trixd status --json | jq '.cache.entries')
    echo "Cache contains $CACHE_COUNT memories"
else
    echo "Daemon is not running"
    trixd start
fi