CLI Reference

Complete reference for all loop-task CLI commands, flags, interval syntax, exit codes, and practical examples.

Commands

loop-task (default)

Open the interactive TUI board. When invoked without a subcommand, loop-task launches the terminal user interface for managing loops, projects, and monitoring execution.

loop-task

loop-task start

Start the background daemon and restore persisted loops from the previous session. The daemon runs as a detached background process and re-hydrates all loops that were active when the daemon was last stopped.

loop-task start

loop-task new <interval> -- <command>

Create a background loop. The command is scheduled according to the given interval and managed by the daemon. The loop persists across daemon restarts.

loop-task new 5m -- curl https://healthcheck.example.com/ping

loop-task run <interval> -- <command>

Run a loop in the foreground (blocking). The command executes repeatedly at the given interval and streams output to the terminal. Press Ctrl+C to stop.

loop-task run 30s -- echo "tick"

loop-task stop <id>

Stop a loop and interrupt its running child process. The loop is removed from the daemon and its persisted state. If a command execution is in progress, the child process receives a termination signal.

loop-task stop abc123

loop-task restart

Kill the daemon and all running loops, then start fresh. All persisted loop configurations are restored, and any previously running loops are re-scheduled.

loop-task restart

loop-task status [--json]

Show status of all loops. By default, displays a formatted table with loop IDs, intervals, projects, last execution time, and current state. Pass --json for machine-readable output.

loop-task status
loop-task status --json

loop-task export [file]

Export all loop configurations to JSON. If a file path is provided, the output is written to that file. If omitted, the JSON is printed to stdout.

loop-task export
loop-task export ./backup-loops.json

loop-task import <file>

Import loop configurations from a JSON file. The imported configs are merged into the daemon's state and trigger a hot-reload - no restart required.

loop-task import ./backup-loops.json

loop-task api

Show HTTP API information - base URL, Swagger UI endpoint, and OpenAPI specification path.

loop-task api

loop-task project list

List all projects. Shows project name, assigned color, and the number of loops assigned to each project.

loop-task project list

loop-task project new <name> [--color <color>]

Create a new project with an optional color assignment.

loop-task project new production --color red
loop-task project new staging

loop-task project rename <id|name> <new-name>

Rename an existing project. Accepts either the project ID or current name as the identifier.

loop-task project rename production prod-infra
loop-task project rename abc123 prod-infra

loop-task project color <id|name> <color>

Change the color assigned to a project. Accepts either the project ID or name.

loop-task project color production blue
loop-task project color abc123 green

loop-task project delete <id|name>

Delete a project. Loops assigned to the project are unassigned but not deleted.

loop-task project delete production
loop-task project delete abc123

loop-task http-host [address]

Show or set the network interface the HTTP API and MCP server bind to. By default, both bind to 0.0.0.0 (all interfaces), making the API reachable remotely. Use this command to restrict to localhost or bind to a specific IP.

# Show current bind host
loop-task http-host

# Restrict to localhost only
loop-task http-host local

# Bind to all interfaces (default)
loop-task http-host all

The HTTP API is unauthenticated. When binding to anything other than 127.0.0.1, secure access at the network layer (SSH, Tailscale, firewall) or restrict to local.

loop-task telemetry

Manage OpenTelemetry configuration. When called without a subcommand, shows the current telemetry status. See OpenTelemetry for the full guide.

# Show status (default)
loop-task telemetry
loop-task telemetry status

loop-task telemetry on

Enable OpenTelemetry instrumentation.

loop-task telemetry on

loop-task telemetry off

Disable OpenTelemetry instrumentation.

loop-task telemetry off

loop-task telemetry endpoint <url>

Set the OTLP export endpoint.

loop-task telemetry endpoint http://127.0.0.1:4318

loop-task telemetry protocol <protocol>

Set the OTLP export protocol.

loop-task telemetry protocol grpc
loop-task telemetry protocol http/protobuf

loop-task telemetry test

Send a diagnostic span to verify the OTLP endpoint is reachable.

loop-task telemetry test

Flags

Flags for new and run

Flag for status

Flag for project new

Global flags

Interval syntax

Examples

Create a background health-check loop

loop-task new 1m -- curl -f https://api.example.com/health

Runs curl every 60 seconds in the background.

Run a database backup loop in the foreground

loop-task run 1h -- pg_dump mydb > /backups/mydb.sql

Executes pg_dump every hour. Output is printed to the terminal. Press Ctrl+C to stop.

Schedule a loop with a specific working directory

loop-task new 30m --project backend --cwd /var/www/app -- ./deploy.sh

Assigns the loop to the backend project and runs ./deploy.sh from /var/www/app.

Create a loop that runs immediately and stops after 5 executions

loop-task new 10s --now --max-runs 5 -- echo "hello"

Runs echo "hello" immediately, then repeats every 10 seconds, stopping automatically after the 5th execution.

Spread loops with phase offset

loop-task new 1h --offset 0m --project workers -- echo "worker A"
loop-task new 1h --offset 30m --project workers -- echo "worker B"

Both loops run every hour, but worker B runs 30 minutes after worker A, spreading the load.

Attach context to a loop

loop-task new 5m --context '{"env":"staging","region":"eu-west-1"}' -- ./sync.sh

Passes structured context data that the command or downstream tools can consume.

Export and import loop configurations

# Export all loops to a file
loop-task export ./backup.json

# Import them on another machine (or after a reset)
loop-task import ./backup.json

Add a description for readability

loop-task new 1d --description "Daily DB vacuum" --project maintenance -- vacuumdb --all

Describes the loop's purpose in the TUI board and status output.

Exit codes