Remote Execution

Nefia's exec command lets you run shell commands on one or more remote hosts simultaneously. Combined with target selector expressions, concurrency control, batching, reruns, and offline queueing, it provides a safe and predictable way to operate on your entire fleet.

Basic Usage

The command to execute must follow a -- separator:

nefia exec [flags] -- <command>

Run a command on a single host using the --host (or -H) shorthand:

nefia exec --host pc-office -- hostname

To run on all connected hosts, use --target all:

nefia exec --target all -- uptime

Target Selection

Use --target (or -t) to select which hosts to run on. The --host (-H) flag is a shorthand for targeting a single host by name.

Selector Expressions

--target is evaluated as a single selector expression. Inside that expression, you can combine unions, exclusions, intersections, regexes, and host lists:

• , for union
• ! for exclusion
• & for intersection
• ~regex for host ID regex matching
• @path/to/file to read host IDs from a file
• - to read host IDs from stdin

# Union
nefia exec --target 'group:webservers,group:workers' -- systemctl status app
 
# Exclude one host from a group
nefia exec --target 'group:webservers,!host:web-03' -- uptime
 
# Regex
nefia exec --target '~^prod-' -- hostname

Session-Scoped Execution

Use --session (or -s) to execute a command within an existing session context:

nefia exec --session <session-id> -- ls -la

This runs the command within the session's sandboxed root directory on the session's host.

Flags Reference

Controlled Rollouts

Use --batch-size and --batch-wait for staged execution across larger fleets:

nefia exec --target group:all --batch-size 5 --batch-wait 10s -- deploy.sh

Use --subset when you want to test a command on a random sample before a broader rollout:

nefia exec --target group:all --subset 3 -- uptime

Offline Queueing and Reruns

Use --when-online to queue commands for hosts that are currently offline:

nefia exec --target group:laptops --when-online --queue-ttl 48h -- softwareupdate --install --all

Use --rerun failure or --rerun success to re-target only the hosts from the most recent multi-host execution outcome.

Concurrency Control

By default, Nefia executes commands on up to 50 hosts in parallel. Use --concurrency (or -c) to adjust this:

# Run on 1 host at a time (serial execution)
nefia exec --target all --concurrency 1 -- apt update
 
# Run on 5 hosts in parallel
nefia exec --target all --concurrency 5 -- apt update

Timeout Management

Set a per-host timeout with --timeout (or -T). If a command exceeds this duration, it is killed and reported as a failure:

nefia exec --target all --timeout 60s -- apt upgrade -y

The default timeout comes from your configuration (typically 30 minutes). Supported units are s (seconds), m (minutes), and h (hours).

Output Formats

Control how results are displayed with --output (or -o):

nefia exec --target all -o human -- df -h /

Fail-Fast Mode

By default, Nefia continues executing on remaining hosts even if some fail. Enable --fail-fast to abort immediately after the first failure:

nefia exec --target group:webservers --fail-fast -- nginx -t

Minimum Success Rate

For operations where partial failure is acceptable, set a minimum success threshold with --min-success-rate. The command reports success only if the percentage of successful hosts meets or exceeds this value:

nefia exec --target all --min-success-rate 0.8 -- systemctl restart app

This is useful in large fleets where a handful of transient failures are expected. If fewer than 80% of hosts succeed, the overall exit code is non-zero.

Progress Reporting

When executing commands across multiple hosts, Nefia displays real-time progress in your terminal.

Multi-host operations show a live progress indicator with success and failure counts:

When all hosts complete, a summary is printed:

Desktop Notifications

Add the --notify flag to receive a desktop notification when the operation completes:

nefia exec --target all --notify -- apt update

You can also enable automatic notifications for long-running operations in your configuration:

defaults:
  notifications:
    enabled: true
    min_duration: "30s"

With this configuration, any operation taking longer than 30 seconds automatically triggers a notification without the --notify flag.

Practical Examples

Rolling restart across a group

nefia exec --target group:webservers --concurrency 1 --timeout 60s -- systemctl restart nginx

Check disk usage on all hosts with JSON output

nefia exec --target all -o json -- df -h / | jq '.results[] | "\(.host): \(.output)"'

Run a command on a specific group

nefia exec --target group:dev-team -- df -h

Validate configuration before deploying

nefia exec --target group:webservers --fail-fast -- nginx -t && \
  nefia exec --target group:webservers --concurrency 1 -- systemctl reload nginx

Related