Background Workflows

Keep servers, watchers, or queue workers running while LoopCLI continues to the next step.

When to use background mode

• Starting a dev server before running integration tests
• Launching npm run watch prior to building assets
• Kicking off a long-running queue consumer while other steps verify state

Add a background step

loopcli loop add-cli devserver "Start Vite" npm \
  --arg run --arg dev \
  --background \
  --shell /bin/zsh \
  --cwd apps/web

Key flags:

• --background – marks the step as non-blocking
• --shell – optional per-step shell (falls back to the global shell)
• --cwd and --env – scope the command to the right directory and secrets

What happens under the hood

• LoopCLI starts the command in a detached process and immediately moves to the next step
• stdout/stderr stream into .loopcli/logs/*-stdout.log and *-stderr.log
• The execution summary shows the PID so you can stop it later if needed

Example excerpt:

→ Executing step: Start Vite (cli)
  ✓ Start Vite running in background (PID 93241)
  Logs: /path/to/.loopcli/logs/start-vite-stdout-....log, ...stderr...

Cleaning up

Background steps continue after the loop finishes. Use kill <pid> (or your shell's equivalent) when you no longer need the process.

Hosted runner support

Background mode is currently available for local execution only. For hosted/cloud execution, use non-blocking alternatives or deploy background processes as separate services.

Related guides

• Shell Overrides
• Screenshot Regression Sweep