status Command

Check FluxLoop system and experiment status.

Overview

The status command provides utilities for checking FluxLoop installation status, configuration validity, and reviewing recent experiments. It's useful for quick health checks and browsing experiment history.

Subcommands

check

Verify FluxLoop system status and configuration.

# Quick status check
fluxloop status check

# Detailed status with verbose output
fluxloop status check --verbose

# Check specific project
fluxloop status check --project my-agent

Options:

Option	Description	Default
--verbose, -v	Show detailed information	false
--project	Project name under FluxLoop root	Current directory
--root	FluxLoop root directory	./fluxloop

What Gets Checked:

1. SDK Installation: Verifies FluxLoop SDK is installed and shows version
2. Collector Connectivity: Attempts to connect to collector service
3. Configuration Files: Checks for required config files in configs/
4. Environment Variables: Verifies API keys and settings

Example Output:

FluxLoop Status Check

╭──────────────────────────────────────────────────────────╮
│ Component  │ Status            │ Details                 │
│ SDK        │ ✓ Installed       │ Version 0.1.6           │
│ Collector  │ ? Unknown         │ URL: http://...         │
│ Config     │ ✓ Found           │ /path/to/configs        │
│ API Key    │ ✓ Set             │ Configured              │
╰──────────────────────────────────────────────────────────╯

Recommendations:
  • Set up API key in .env file

Status Indicators:

Symbol	Meaning
✓	Component working correctly
✗	Component has errors
-	Component not configured
?	Status unknown/uncertain

Common Issues:

Issue	Details	Recommendation
SDK not installed	FluxLoop SDK missing	pip install fluxloop
Config incomplete	Missing config files	fluxloop init project
API key not set	No FLUXLOOP_API_KEY	Set in .env file
Collector error	Cannot connect	Check collector URL

---

experiments

List recent experiments and their results.

# List recent experiments (default: 10 most recent)
fluxloop status experiments

# Show more experiments
fluxloop status experiments --limit 20

# Check specific output directory
fluxloop status experiments --output ./my-experiments

# Check for specific project
fluxloop status experiments --project production-agent

Options:

Option	Description	Default
--output, -o	Directory containing experiment results	./experiments
--project	Project name	Current
--root	FluxLoop root directory	./fluxloop
--limit, -l	Number of experiments to show	10

Example Output:

Recent Experiments (showing 3 of 15)

╭─ exp_20250117_143022 ───────────────────────────────╮
│ Name: my_agent_experiment                            │
│ Date: 2025-01-17 14:30:22                           │
│ Runs: 50                                            │
│ Success Rate: 94.0%                                  │
│ Avg Duration: 234ms                                  │
╰──────────────────────────────────────────────────────╯

╭─ exp_20250117_120015 ───────────────────────────────╮
│ Name: my_agent_experiment                            │
│ Date: 2025-01-17 12:00:15                           │
│ Runs: 100                                           │
│ Success Rate: 89.0%                                  │
│ Avg Duration: 312ms                                  │
╰──────────────────────────────────────────────────────╯

📁 exp_20250116_093045 (no summary available)

Experiment Information:

For each experiment with a summary.json file, displays:

• Name: Experiment name from configuration
• Date: Timestamp when experiment ran
• Runs: Total number of test runs executed
• Success Rate: Percentage of successful completions
• Avg Duration: Average execution time in milliseconds

When No Experiments Found:

No experiments found in: ./experiments

Run an experiment first: fluxloop run experiment

---

traces

List recent traces from experiments.

# View recent traces (requires collector service)
fluxloop status traces

# View traces for specific experiment
fluxloop status traces my_experiment_id

# Limit number of traces shown
fluxloop status traces --limit 20

Arguments:

Argument	Description
experiment_id	Optional experiment ID to filter traces

Options:

Option	Description	Default
--limit, -l	Number of traces to show	10

Note:

This feature requires a running collector service. When the collector is not available:

Trace viewing requires collector service

This feature will be available when the collector is running.
For now, check the experiment output directories for trace data.

Alternative: View Traces Locally

Until the collector service is running, view traces in experiment directories:

# List trace files
ls experiments/exp_*/artifacts/

# View trace summary
cat experiments/exp_*/summary.json | jq

# View individual traces
cat experiments/exp_*/artifacts/traces.jsonl | head -n 5

---

Common Workflows

Pre-Experiment Health Check

Before running experiments, verify everything is configured:

# Quick status check
fluxloop status check

# Or use doctor for comprehensive diagnostics
fluxloop doctor

# Verify configuration
fluxloop config validate

Post-Experiment Review

After running experiments, review results:

# List recent experiments
fluxloop status experiments --limit 5

# Parse latest experiment for detailed analysis
fluxloop parse experiment experiments/latest_run_*/

# Evaluate results
fluxloop evaluate experiment experiments/latest_run_*/

Monitoring Experiment History

Track experiment performance over time:

# List all recent experiments
fluxloop status experiments --limit 20

# Check specific project's experiments
fluxloop status experiments --project production-agent

# Compare with specific output directory
fluxloop status experiments --output ./archived-experiments

Troubleshooting Setup Issues

When things aren't working, use status commands to diagnose:

# 1. Check system status
fluxloop status check --verbose

# 2. Verify environment
fluxloop config env

# 3. Run full diagnostics
fluxloop doctor

# 4. Validate configuration
fluxloop config validate

---

Status vs Doctor

Both status check and doctor verify system health, but with different focuses:

Aspect	status check	doctor
Focus	Quick health check	Comprehensive diagnostics
Checks	SDK, Collector, Config, API Key	Python, CLI, SDK, MCP, Index, Config
Output	Concise table	Detailed panels with recommendations
Speed	Fast	Thorough
Use Case	Quick verification	Deep troubleshooting

When to Use Each:

Use status check:

• Quick health verification before running experiments
• Checking if basic setup is complete
• Verifying configuration after changes

Use doctor:

• Initial setup verification
• Troubleshooting installation issues
• Verifying MCP server and index
• Complete environment diagnostics

---

Output Interpretation

SDK Status

Status	Meaning	Action
✓ Installed	SDK found and loaded	None needed
✗ Not installed	SDK missing	pip install fluxloop

Collector Status

Status	Meaning	Action
✓ Connected	Collector reachable	None needed
? Unknown	Cannot verify (offline mode OK)	Verify URL if needed
✗ Error	Connection failed	Check FLUXLOOP_COLLECTOR_URL

Config Status

Status	Meaning	Action
✓ Found	All required configs present	None needed
- Incomplete	Missing config files	fluxloop init project
✗ Invalid	Config syntax errors	Fix YAML syntax

API Key Status

Status	Meaning	Action
✓ Set	API key configured	None needed
- Not set	No API key found	Set in .env file

---

Tips

Quick Status Alias

Create a shell alias for faster checks:

# Add to ~/.bashrc or ~/.zshrc
alias fls='fluxloop status check'
alias fle='fluxloop status experiments'

Usage:

fls         # Quick status check
fle -l 20   # List 20 recent experiments

Automated Health Checks

Add status checks to scripts:

#!/bin/bash
# run_experiment.sh

# Verify system ready
if ! fluxloop status check --verbose; then
    echo "System not ready!"
    exit 1
fi

# Run experiment
fluxloop run experiment

# Show results
fluxloop status experiments --limit 1

Monitoring Multiple Projects

Check status across different projects:

for project in agent-v1 agent-v2 agent-v3; do
    echo "=== $project ==="
    fluxloop status check --project $project
    echo
done

---

Exit Codes

All status subcommands follow consistent exit code patterns:

Exit Code	Meaning
0	Status check completed (doesn't mean all checks passed)
1	Invalid arguments or runtime error

Note: status check exits with 0 even if some components have issues. Check the output to see actual component status.

---

See Also

• doctor Command - Comprehensive environment diagnostics
• config Command - Configuration management
• run Command - Execute experiments
• parse Command - Parse experiment results
• evaluate Command - Evaluate experiment outputs