ucli agent guide

CLI: ucli [global flags] <group> <command> [args...]

Recommended defaults

ucli --output json --quiet <group> <command>

• --output json for machine-readable output
• --quiet to suppress decorative text
• --fields to shrink payloads
• --filter and --sort to shape data before it hits your context

Guardrails

• Prefer read-only commands first. Inspect before acting.
• Use --yes only in deliberate automation paths, never speculatively.
• Pair destructive actions with explicit identifiers. No fuzzy matching in the shell.
• Re-fetch state after any mutation. Do not trust a prior cache.
• Treat exit code 0 as success. Non-zero: capture stderr, retry only on transient failures.

Command groups

Workflow: health check

ucli system info --output json --quiet
ucli system health --output json --quiet
ucli array status --output json --quiet
ucli services status --output json --quiet

1. Fetch each separately. Fail fast on non-zero exits.
2. Summarize array state, service state, resource pressure, warnings.
3. Only pull logs if the snapshot shows trouble.

Workflow: container management

# list running
ucli containers list --output json --quiet --fields id,names,state,status --sort names:asc

# inspect one
ucli containers inspect <id> --output json --quiet

# restart
ucli containers restart <id> --yes --output json --quiet

1. Resolve target by id or names.
2. Inspect current state.
3. Execute with --yes when confirmation would block automation.
4. Re-read status after mutation.

Anti-patterns

• Don't parse human-readable output. Always use --output json.
• Don't assume partial success from human-readable text. Check exit codes.
• Don't retry on non-transient errors (auth, bad arguments, missing resources).
• Don't skip --fields on large result sets. Token waste adds up fast.
• Don't chain mutations without re-fetching state between them.
• Don't use --force unless you understand exactly what it skips.

Configuration

Default config path: ~/.config/ucli/config.yaml

default_profile: lab
profiles:
  lab:
    host: http://192.168.1.10:7777
    apiKey: YOUR_API_KEY
    output: json
    timeout: 30

Prefer --host and --api-key explicitly for isolated jobs, --profile <name> for stable environments.

ucli agent guide

CLI: ucli [global flags] <group> <command> [args...]

Recommended defaults

ucli --output json --quiet <group> <command>

• --output json for machine-readable output
• --quiet to suppress decorative text
• --fields to shrink payloads
• --filter and --sort to shape data before it hits your context

Guardrails

• Prefer read-only commands first. Inspect before acting.
• Use --yes only in deliberate automation paths, never speculatively.
• Pair destructive actions with explicit identifiers. No fuzzy matching in the shell.
• Re-fetch state after any mutation. Do not trust a prior cache.
• Treat exit code 0 as success. Non-zero: capture stderr, retry only on transient failures.

Command groups

Workflow: health check

ucli system info --output json --quiet
ucli system health --output json --quiet
ucli array status --output json --quiet
ucli services status --output json --quiet

1. Fetch each separately. Fail fast on non-zero exits.
2. Summarize array state, service state, resource pressure, warnings.
3. Only pull logs if the snapshot shows trouble.

Workflow: container management

# list running
ucli containers list --output json --quiet --fields id,names,state,status --sort names:asc

# inspect one
ucli containers inspect <id> --output json --quiet

# restart
ucli containers restart <id> --yes --output json --quiet

1. Resolve target by id or names.
2. Inspect current state.
3. Execute with --yes when confirmation would block automation.
4. Re-read status after mutation.

Anti-patterns

• Don't parse human-readable output. Always use --output json.
• Don't assume partial success from human-readable text. Check exit codes.
• Don't retry on non-transient errors (auth, bad arguments, missing resources).
• Don't skip --fields on large result sets. Token waste adds up fast.
• Don't chain mutations without re-fetching state between them.
• Don't use --force unless you understand exactly what it skips.

Configuration

Default config path: ~/.config/ucli/config.yaml

default_profile: lab
profiles:
  lab:
    host: http://192.168.1.10:7777
    apiKey: YOUR_API_KEY
    output: json
    timeout: 30

Prefer --host and --api-key explicitly for isolated jobs, --profile <name> for stable environments.