LoopCLI Command Reference

Who This Guide Is For

LoopCLI is designed to feel great for two types of builders:

• Developers get power features: visual dashboards with keyboard shortcuts, verbose JSON output, saved stdout/stderr logs, and filters/flags for scripting and CI. Nothing is locked away—--plain keeps automation clean, and the dashboards surface the same data you’d expect from code-first tools.
• Non-coders & growth teams get a guided experience: a friendly welcome screen, interactive loop creation wizard, clear execution summaries, and point-and-click log browsing. Helpful hints live in every footer so you always know the next key to press, and you never have to touch the filesystem to inspect results.

Use the command sections below at your own pace—start with the defaults, then layer in the advanced flags when you’re ready.

Interface Modes

• loopcli loop mode --show — display whether you’re in simple or advanced mode.
• loopcli loop mode --simple — enable simple mode (minimal shortcuts, guided prompts).
• loopcli loop mode --advanced — restore the full keyboard-driven experience.
• Set LOOPCLI_SIMPLE_MODE=1 in your shell to enforce simple mode (or 0 to force advanced) across sessions.
• On first launch, LoopCLI starts in simple mode; the welcome screen highlights the difference and shows how to switch with loopcli loop mode (revisit it anytime with loopcli welcome).
• When simple mode is active, the CLI shows a one-time yellow reminder before visual screens so you know how to switch back to advanced controls.

Welcome to the comprehensive command reference for LoopCLI. This document pairs nicely with the hosted runner guide and the getting started tutorial. Every section below includes descriptions, example invocations, and notes on how the CLI behaves when you are offline versus connected to the hosted platform.

1. Installation & Setup

Install

npm install -g loopcli

Example output:

added 120 packages in 3s

Verify installation

loopcli --version

Example output:

LoopCLI v0.1.2

Update to latest version

To update LoopCLI to the latest version, run:

npm update -g loopcli

Or reinstall to force the latest version:

npm install -g loopcli@latest

To check if an update is available:

npm outdated -g loopcli

Example output when update is available:

Package  Current  Wanted  Latest  Location
loopcli    0.1.2   0.1.6   0.1.6  global

Tip: After updating, run loopcli --version to confirm the new version is active. If you see the old version, you may need to clear npm's cache with npm cache clean --force and reinstall.

First run welcome experience

• Running loopcli with no arguments launches an interactive Ink welcome screen the first time you use a new version.
• Press space or q to dismiss it. The screen highlights quick-start commands and mirrors the CLI’s visual design direction.
• Revisit it later with loopcli welcome (pass --reset to force first-run mode).
• Set LOOPCLI_SKIP_WELCOME=1 in CI or headless environments to bypass the welcome automatically.

Configuration directory

• The CLI stores configuration in ~/.loopcli/config.json (override with LOOPCLI_CONFIG_DIR).
• The file includes the API base URL, API token, and active project ID.

Environment overrides

• Use LOOPCLI_API_URL to point the CLI at a staging or local environment.

  export LOOPCLI_API_URL="https://staging-loopcli.example.com/api"
  

Configure the default shell

LoopCLI runs CLI steps using your login shell. View or update the shell with:

loopcli loop shell --show
loopcli loop shell --set /bin/zsh
loopcli loop shell --reset

Per-step overrides are available via loop add-cli --shell.

Authentication

loopcli auth login

• Opens a browser window for device approval. Approve the request to issue a new API token (stored in ~/.loopcli/config.json).
• Use --no-browser to copy/paste the verification URL manually, or supply credentials explicitly with --email/--password if the browser isn’t available.
• loopcli auth logout revokes the key and clears local credentials.
• loopcli auth whoami verifies the current token is valid and prints the user profile.
• loopcli status shows overall health (auth state, configured project, API endpoint).

Tip: If you accidentally point to the wrong environment or a token expires, run loopcli auth logout followed by loopcli auth login.

2. Project Management

Projects are synchronized with the hosted API when you are logged in. Offline, the CLI uses the local cache in ~/.loopcli/projects/.

Create

loopcli project create growth-automation

• Example output:

✓ Project created
Name: growth-automation
Project ID: 87c0e7d2-...

• When authenticated, this creates the project via /api/projects and stores a copy locally.
• Offline, it creates a local project only and marks it for sync later.

List

loopcli project list

• Example output:

→ growth-automation (87c0e7d2-...)
  Created: 2025-02-13
  Updated: 2025-02-13

Current project: growth-automation

• Displays remote projects (if authenticated) and refreshes the local cache.
• Shows the current project path, creation date, and basic metadata.

Use

loopcli project use growth-automation

• Updates the active project in the config file.
• Subsequent commands operate in the context of this project.

Initialize current directory

loopcli project init growth-automation

• Creates .loopcli/project.json in the current folder (or uses an existing project).
• Links the directory to the project so loop definitions live under .loopcli/loops/.

Offline vs online behavior

• Commands always write to local cache.
• When authenticated, the CLI attempts to sync remote state after each command and logs to stderr if the sync fails.

3. Loop Management

Create

loopcli loop create enrich-leads --description "Enrich leads with Clearbit"

• Supports --interactive to launch the Loop Builder wizard (visual Ink UI in TTYs, arrow-key driven) or fall back to prompts when visuals are disabled.
• In the wizard, press a to add steps, d to delete, enter to finish, q to cancel (steps can be added later with loop add-*).
• Creates the loop both locally and remotely (if authenticated).

List

loopcli loop list

• Shows loops in the current project with step counts and timestamps.
• Automatically pulls latest loops from the API when logged in.
• When run in a TTY, opens the visual Loop Navigator: use ↑/↓ to inspect loops, enter to close, q to quit.
• Pass --plain or set LOOPCLI_SKIP_VISUAL=1 for traditional text output (useful for scripts/CI).

Add HTTP step

loopcli loop add-http enrich-leads "Fetch Lead" GET https://api.example.com/leads \
  -H "Authorization: Bearer $TOKEN"

• Output confirmation appears when the step is saved locally (and synced remotely if authenticated).
• Adds an HTTP step to the loop JSON and syncs it to the API when authenticated.
• Use multiple -H flags for additional headers; -d to supply JSON payload for POST/PUT.

Add CLI step

loopcli loop add-cli enrich-leads "Sanitize Data" "python scripts/sanitize.py" \
  --env MODE=clean --shell /bin/zsh

• CLI steps run locally and in the hosted runner (hosted mode uses a restricted sandbox). Ensure required binaries and environment variables exist in the hosted environment.
• Additional flags:
  • --arg <value> (repeatable) to append positional arguments.
  • --env KEY=value to inject environment variables.
  • --cwd <path> to change the working directory for the command.
  • --shell <path> to override the shell for this specific step.
  • --background to launch the command in the background (local mode only).

Background mode

loopcli loop add-cli devserver "Start Vite" "npm run dev" --background

• LoopCLI starts the command and immediately continues to the next step.
• Stdout/stderr stream into .loopcli/logs/ and the execution summary shows the PID.
• Background mode works for local execution. For hosted execution, use non-blocking alternatives or separate services.

Edit

loopcli loop edit enrich-leads

• Opens .loopcli/loops/enrich-leads.json in $EDITOR.
• On save, the CLI syncs the entire definition to the API (even offline changes).
• Ideal for bulk edits or advanced step configuration.

4. Executing Loops

Local mode (default)

loopcli loop run enrich-leads

• Example result:

==================================================
EXECUTION SUMMARY
==================================================
✓ Status: SUCCESS
⏱  Total Duration: 1200ms
📊 Steps Executed: 3/3

• Executes steps sequentially on your machine.
• Shows success/failure, per-step details (with --verbose), and total duration.
• In TTYs, displays the local execution dashboard (summary + per-step cards). Use --plain or LOOPCLI_SKIP_VISUAL=1 for classic logs.
• CLI steps capture stdout/stderr; verbose mode prints the full output inline and always saves large logs to .loopcli/logs/ with the file path shown in the dashboard.
• In the dashboard, use ↑/↓ to highlight a step, press o for stdout or O for stderr (if captured) to view logs instantly.

Cloud mode

loopcli loop run enrich-leads --cloud --wait --interval 3000 --timeout 60000

• Queues the loop on the hosted runner via /run endpoint.
• --wait polls the API until the execution completes.
• --interval sets polling frequency (ms); default 2000.
• --timeout aborts waiting after the specified milliseconds.
• When running in a TTY, --wait opens the Execution Monitor dashboard (live status, step cards, cancel with q). Use --plain or LOOPCLI_SKIP_VISUAL=1 for legacy text output.
• --json prints the final execution JSON result.

Waiting on an existing execution

loopcli loop wait exec_01HXYZ...

• Polls until completion using the same options as --wait.
• Helpful when you queue runs from CI/CD and want to monitor them separately.

5. Hosted Runner Controls

Note: When you deploy a loop, hosted execution becomes your default runtime. Local runs are still available with loopcli loop run, but scheduled and queued runs execute in LoopCLI’s managed worker unless you explicitly disable deployment.

Deploy

loopcli loop deploy enrich-leads --schedule "0 * * * *" --activate

• Example result:

✓ enrich-leads deployed
Schedule: 0 * * * *
Status: Active
Remote loop ID: 3d0f7e12-...

• Updates the loop definition and schedule in the hosted runner.
• --disable removes the active flag (loop stays deployed but won’t auto-run).
• When you include --schedule, the dashboard upserts the cron into loop_schedules and calculates the next run timestamp immediately. A shared orchestrator claims due schedules every minute; bring your own cron trigger (see Cloud Deployment) to call the scheduler and worker endpoints.
• --json prints raw API response.

Monitor executions

• loopcli loop executions --loop enrich-leads --page 1 --limit 20
• loopcli loop execution exec_01HXYZ... --json
• loopcli loop wait exec_01HXYZ...
• Returns status, action counts, per-step summaries, errors, and timestamps.
• In TTYs the executions list opens the visual history dashboard (↑/↓ to inspect, n/p to paginate, q to exit). Use --plain or LOOPCLI_SKIP_VISUAL=1 for text output.
• loopcli loop execution <id> now opens a detail screen (status, timeline, payload, per-step output) when run in a TTY. Press enter or q to exit; pass --plain or set LOOPCLI_SKIP_VISUAL=1 for the traditional text view.
• loopcli loop logs lists saved CLI stdout/stderr captures (.loopcli/logs/). Interactive mode lets you browse files and open them in-view; --plain prints the file paths. Add --loop, --step, --stream, or --limit to narrow results. Use --latest to open the newest log immediately or pass loopcli loop logs <filename> to view a specific file.

Worker commands

• loopcli loop scheduler:run – manually trigger the orchestrator (/api/internal/scheduler/run) to claim due schedules and queue executions.
• loopcli loop worker:run – manually trigger the worker endpoint (processes one queued job). Useful for debugging cron issues.
• loopcli loop worker:schedule – prints instructions and sample cron JSON for wiring both the scheduler and worker into Supabase Scheduler, Vercel Cron, GitHub Actions, etc.
• Hosted runner executes HTTP steps with retries and CLI steps in a restricted environment (commands must already exist on the server, no interactive prompts).

6. Vault & Secrets Management

• loopcli secret list — display secrets stored in the active project along with rotation timestamps.
• loopcli secret add <name> --value <value> — create a new secret. Omit --value and pipe stdin if you prefer not to pass credentials inline.
• loopcli secret reveal <name> — decrypt a secret once and print it to the terminal (ideal for manual debugging or regenerating env files).
• loopcli secret export [--stdout] — dump every secret in plaintext JSON (matching the dashboard “Export JSON” button). Store the file securely and delete it when you’re done.
• loopcli secret import <file> — bulk create/overwrite secrets from a prior export. Pass --skip-existing to leave matching names untouched.
• loopcli secret delete <name> — remove a secret (add --force for non-interactive workflows).
• loopcli secret rekey — admin-only command that re-encrypts every secret with the latest vault keyset (mirrors the dashboard “Rekey All” control).
• Placeholders inside loop definitions—{{secret:stripe_secret_key}} or {{secrets:slack_webhook}}—resolve automatically before execution. During hosted runs, every secret also appears as an environment variable using uppercase snake case (e.g. STRIPE_SECRET_KEY) so CLI steps can reference $STRIPE_SECRET_KEY without extra wiring.
• Secrets stay encrypted at rest with AES-256-GCM. Only the project owner (and hosted runner for that project) can decrypt them, and access attempts update the “last accessed” timestamp visible in the dashboard.

7. Templates

• loopcli loop template:screenshot <loop> — scaffold a Playwright-based screenshot regression loop. Use --install, --test, and optional --report to customize commands.

8. Troubleshooting

• 401 Unauthorized: Run loopcli auth login to refresh your token.
• Project not found: Ensure you are inside a directory with .loopcli/project.json or run loopcli project init.
• Hosted run stuck in queued: Confirm your cron/queue is calling both /api/internal/scheduler/run and /api/internal/runner/process; try loopcli loop scheduler:run then loopcli loop worker:run to force a manual tick.
• CLI steps failing in hosted mode: Hosted runner currently supports HTTP steps only; CLI steps will report unsupported status.
• RangeError: Maximum call stack size exceeded from stubborn-fs or conf: Upgrade to LoopCLI ≥0.1.2 (the config store now uses ~/.loopcli/config.json). If the error persists, delete the legacy ~/Library/Preferences/loopcli-nodejs/ folder and rerun the CLI.
• Reset local state: Remove .loopcli/ from project directory and run loopcli project list to re-sync.

1. Installation & Setup

• Install globally: npm install -g loopcli
• Verify version: loopcli --version
• Config file lives at ~/.loopcli/config.json
• Override API endpoint via LOOPCLI_API_URL
• Authenticate: loopcli auth login

2. Authentication Commands

• loopcli auth login – opens the browser for device approval (fallback with --email/--password when necessary)
• When prompted, approve the login at /auth/device?token=... (the dashboard shows the short user code, lets you label the device, and works on mobile).
• loopcli auth logout – clears local token and revokes remote key
• loopcli auth status – shows whether a token is present and valid
• loopcli auth whoami – fetches user profile from API
• loopcli status – aggregate auth/project summary

3. Project Management

• loopcli project create <name> – creates project locally & remotely (if authenticated)
• loopcli project list – synced with /projects API
• loopcli project use <id|name> – switches active project (updates config)
• loopcli project init [name] – initialize .loopcli in current directory
• Offline behavior: commands read/write local cache; sync occurs once authenticated

4. Loop Management

• loopcli loop create <name> (--description, --interactive)
• loopcli loop list
• loopcli loop add-http, loopcli loop add-cli
• loopcli loop edit <name> – opens JSON; saves to API when authenticated
• loopcli loop delete <name> (not yet available)

5. Executing Loops

• loopcli loop run <name>
  • Local mode (default) – prints execution summary
  • --cloud – queue hosted runner, with options --wait, --interval, --timeout, --json
• loopcli loop wait <executionId> – poll remote execution until completion

6. Hosted Runner Management

• loopcli loop deploy <name> – push definitions to hosted runner (flags: --schedule, --activate, --disable, --json)
• loopcli loop executions – list recent cloud runs (filters, pagination, JSON)
• loopcli loop execution <id> – inspect step details, errors
• loopcli loop worker:run – manually trigger worker endpoint (requires RUNNER_WORKER_SECRET)

7. Troubleshooting & Tips

• Invalid token / 401 – re-run loopcli auth login
• Stale local state – remove .loopcli and re-sync with loopcli project list
• Hosted runs stuck in queued – ensure worker cron is calling /api/internal/runner/process