Skip to main content

Overview

All Lua CLI commands now support non-interactive mode, enabling seamless automation for:
  • AI IDEs (Cursor, GitHub Copilot, Windsurf, etc.)
  • CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
  • Shell scripting and automation
  • Programmatic agent management
Non-interactive mode bypasses all prompts by providing arguments and flags directly on the command line.
Every command now has non-interactive options with consistent naming patterns.

AI Agent Building Guide

Building with Cursor, Windsurf, or GitHub Copilot? See the complete AI Agent Building Guide for the full end-to-end workflow including authentication, testing strategies, sandbox vs production, common gotchas, and debugging.

Design Patterns

Consistent Option Naming

All commands follow these patterns:

Action Arguments

Many commands accept an action as the first argument:

CI/CD Mode (—ci flag)

The global --ci flag makes the CLI fail loudly on missing required arguments instead of silently prompting (which fails in non-TTY environments).
In CI/CD pipelines and non-TTY environments (piped input, background jobs), interactive prompts silently fail, causing commands to cancel without clear error messages. The --ci flag prevents this by throwing errors when required arguments are missing:

Usage

The --ci flag is a global flag that must come before the command:

When to Use

Always use --ci in automated environments:
Why: Ensures missing flags cause immediate, clear failures instead of silent hangs.

Behavior Differences

Auto-Detection

Even without --ci, the CLI automatically detects non-TTY environments and shows a warning:
However, this still allows the command to continue (and likely fail silently). Using --ci prevents this by failing immediately.

Complete Command Reference

Project Setup

Initialize a new project without prompts:

Development & Testing

Test skills, webhooks, or jobs without prompts:

Deployment

Push components without prompts:

Entity Management

Manage skills without prompts:

Configuration

Manage environment variables without prompts:

Viewing & Debugging

View logs without prompts:

Authentication & Utilities

Authentication commands with —force:

Marketplace

lua marketplace [noun] [action], where noun is skill or template. See the Marketplace Command reference for the full flag set.
Publish, manage, and install skills — all in one flat action namespace:

Example Workflows

AI IDE Workflow (Cursor, Copilot)

When an AI assistant needs to manage your agent:

GitHub Actions CI/CD

Post-deploy verification (CI-friendly)

After any production deploy, run a 3-line probe to confirm the new version is healthy. This is the CI version of the canonical post-deploy debug loop:
Wire the third line into your pipeline’s exit code so a non-zero error count fails the build:
Silencing post-action hints in CI. The CLI prints ✨ Tip: / 💡 Diagnose: lines and a quiet agent_error probe summary after each command. They’re useful interactively but noisy when CI captures only command output. Set LUA_NO_HINTS=1 to silence all of them:

Bash Scripting

Multi-Component Deployment

Exit Codes

All commands return consistent exit codes: Use exit codes in scripts:

JSON Output

Commands with --json output machine-readable JSON:

Best Practices

In automated pipelines, always use --force to skip confirmations:
Use lua sync --check in CI to fail builds on drift:
When processing output programmatically, use --json:
Use dynamic versions in CI:

CLI Overview

All available commands

Skill Management

init, test, push, deploy details

Sync Command

Drift detection details

Environment Variables

Managing configuration