Skip to content

list.md

Latest commit

 

History

History
349 lines (275 loc) · 8.79 KB

list.md

File metadata and controls

349 lines (275 loc) · 8.79 KB
Raw

muster list

List resources in the Muster environment.

Synopsis

muster list [RESOURCE_TYPE] [OPTIONS]

Description

The list command displays resources managed by Muster, providing an overview of their current state and configuration. It supports multiple resource types and output formats.

Prerequisites: The aggregator server must be running (muster serve) before using this command.

Resource Types

Resource Type Description Example
service List all services with their status muster list service
mcpserver List all MCP server definitions muster list mcpserver
workflow List all workflow definitions muster list workflow
workflow-execution List all workflow execution history muster list workflow-execution

Options

Output Control

  • --output, -o (string): Output format (table|json|yaml)
    • Default: table
  • --quiet, -q: Suppress non-essential output
    • Default: false

Configuration

  • --config-path (string): Custom configuration directory path
    • Default: ~/.config/muster

Examples

Listing Services

# List all services
muster list service

# Example output:
# NAME          STATUS    CREATED
# web-app-1     Running   2h ago
# database      Stopped   1d ago
# monitoring    Running   3h ago

Listing MCP Servers

# List all MCP server configurations
muster list mcpserver

# Example output (when authenticated):
# NAME         STATE          SESSION         TYPE
# kubernetes   Connected      Authenticated   streamable-http
# prometheus   Auth Required  Pending Auth    streamable-http
# github       Failed         -               stdio

# Use wide output for more details:
muster list mcpserver -o wide

The output shows:

  • STATE: Infrastructure state from CRD status
    • Connected: Server is reachable and authenticated
    • Auth Required: Server is reachable but needs authentication (returned 401)
    • Connecting: Attempting to connect
    • Failed: Server cannot be reached
    • Running/Stopped: For stdio (local) servers
  • SESSION: Per-user authentication state (only shown when logged in)
    • Authenticated: Successfully authenticated to this server
    • Pending Auth: Server requires authentication
    • Expired: Token has expired
    • -: No session state available

Listing Workflows

# List all workflow definitions
muster list workflow

# Example output:
# NAME           DESCRIPTION              STEPS   LAST_EXECUTED
# deploy-app     Application deployment   5       1h ago
# backup-db      Database backup          3       6h ago
# scale-service  Service scaling          2       Never

Listing Workflow Executions

# List workflow execution history
muster list workflow-execution

# Example output:
# ID                    WORKFLOW     STATUS     STARTED        DURATION
# abc123-def456-789     deploy-app   Success    2h ago         45s
# def456-789abc-123     backup-db    Success    6h ago         2m30s
# 789abc-123def-456     deploy-app   Failed     1d ago         15s

Output Formats

Table Format (Default)

Clean, human-readable tabular output:

muster list service
# NAME        STATUS    CREATED
# my-app      Running   2m ago
# my-db       Stopped   1h ago

JSON Format

Structured data for programmatic processing:

muster list service --output json
# {
#   "services": [
#     {
#       "name": "my-app",
#       "status": "Running",
#       "created": "2024-01-07T10:00:00Z",
#       "parameters": {
#         "image": "nginx:latest",
#         "replicas": 3
#       }
#     }
#   ]
# }

YAML Format

YAML output for configuration management:

muster list workflow --output yaml
# workflows:
# - name: deploy-app
#   description: Application deployment workflow
#   steps: 5
#   created: "2024-01-07T09:00:00Z"

Filtering and Information

Service Status Information

Services are displayed with comprehensive status information:

muster list service
# NAME          STATUS      CREATED    UPTIME
# frontend      Running     2h ago     1h 45m
# backend       Starting    5m ago     -
# database      Stopped     1d ago     -
# cache         Error       1h ago     -

Status Values:

  • Running: Service is active and healthy
  • Starting: Service is in startup phase
  • Stopped: Service is intentionally stopped
  • Error: Service encountered an error
  • Unknown: Service status cannot be determined

MCP Server Information

MCP servers display connection and tool information:

muster list mcpserver --show-details
# Name          Type    State     Tools   AutoStart   Port
# kubernetes    local   Running   15      true        1234
# prometheus    local   Running   8       true        1235
# github        local   Stopped   12      false       -
# local-tools   local   Error     0       true        -

Workflow Information

Workflows show execution statistics and metadata:

muster list workflow
# NAME           STEPS   EXECUTIONS   SUCCESS_RATE   LAST_RUN
# deploy-app     5       23           95.7%          1h ago
# backup-db      3       156          100%           6h ago
# scale-service  2       0            -              Never

Resource Relationships

Service Dependencies

Understanding relationships between resources:

# List services to see service status
muster list service

# List MCP servers to see tool availability
muster list mcpserver
# Shows which tools are available

Common Use Cases

System Overview

# Get complete system overview
muster list service
muster list mcpserver
muster list workflow

Health Check

# Check system health
muster list service | grep -v Running  # Find non-running services
muster list mcpserver | grep -v Running  # Find failed MCP servers

Resource Planning

# Understand resource usage
muster list workflow --output json | jq '.workflows[] | {name, executions, successRate}'

Automation Scripting

# Get running services for scripts
RUNNING_SERVICES=$(muster list service --output json | jq -r '.services[] | select(.status=="Running") | .name')

# Get available tools count
TOOL_COUNT=$(muster list mcpserver --output json | jq '[.mcpServers[] | .tools] | add')

Troubleshooting

Empty Results

muster list service
# No services found

# Possible causes:
# 1. No services created yet
muster create service test-service

# 2. Server not running
muster serve  # In another terminal

# 3. Configuration issue
muster list service --config-path ~/.config/muster

Connection Issues

muster list service
# Error: failed to connect to aggregator

# Solution: Verify server is running
ps aux | grep "muster serve"
curl http://localhost:8080/api/v1/status

Permission Issues

muster list service
# Error: permission denied

# Solution: Check configuration permissions
ls -la ~/.config/muster/
chmod 755 ~/.config/muster

Exit Codes

Code Meaning
0 Resources listed successfully
1 General error or invalid arguments
2 Invalid resource type
3 Configuration error
4 Connection error (server not running)

Auto-Completion

The list command supports tab completion:

# Resource types
muster list [TAB]
# Suggestions: service, mcpserver, workflow, workflow-execution

Performance Considerations

Large Environments

For environments with many resources:

# Use quiet mode for faster output
muster list service --quiet

# Use JSON for programmatic processing
muster list service --output json | jq '.services | length'

# Filter results programmatically
muster list service --output json | jq '.services[] | select(.status=="Running")'

Integration Patterns

Monitoring Scripts

#!/bin/bash
# Check for failed services
FAILED_SERVICES=$(muster list service --output json | jq -r '.services[] | select(.status=="Error") | .name')
if [ -n "$FAILED_SERVICES" ]; then
  echo "Failed services detected: $FAILED_SERVICES"
  exit 1
fi

Workflow Monitoring

# Check recent workflow executions
muster list workflow-execution --output json | \
  jq '.executions[] | select(.started > "2024-01-07T00:00:00Z")'

Related Commands

  • get - Get detailed information about specific resources
  • create - Create new resources
  • start - Start services or execute workflows
  • check - Check resource availability
  • agent - Interactive exploration with REPL mode

Advanced Usage

Custom Queries

# Count services by status
muster list service --output json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

# List workflows by success rate
muster list workflow --output json | jq '.workflows | sort_by(.successRate) | reverse'