CLI Commands

`al new <name>`

Creates a new Action Llama project. Runs interactive setup to configure credentials and LLM defaults.

npx @action-llama/action-llama new my-project

Creates:

my-project/package.json — with @action-llama/action-llama dependency
my-project/.gitignore
my-project/.workspace/ — runtime state directory
Credential files in ~/.action-llama/credentials/

After setup, create agents by following Creating Agents.

`al doctor`

Checks all agent credentials and interactively prompts for any that are missing. Discovers agents in the project, collects their credential requirements (plus any webhook secret credentials), and ensures each one exists on disk. Also generates a gateway API key if one doesn’t exist yet (used for dashboard and CLI authentication). Additionally validates webhook trigger field configurations to catch common errors like:

Using repository instead of repos
Misspelled field names
Invalid field types

This helps catch configuration mistakes early and ensures webhook triggers are properly configured.

al doctor -p .
al doctor -p ./my-project

Option	Description
`-p, --project <dir>`	Project directory (default: `.`)

`al creds ls`

Lists all stored credentials grouped by type, showing field names but not values.

al creds ls

Example output:

  Anthropic API Key (anthropic_key)
    anthropic_key  (token)

  GitHub Token (github_token)
    github_token  (token)

  GitHub Webhook Secret (github_webhook_secret)
    github_webhook_secret:myapp  (secret)
    github_webhook_secret:staging  (secret)

Default instances are shown without the :default suffix.

`al creds add <ref>`

Add or update a credential. Runs the interactive prompter with validation for the credential type.

al creds add github_token              # adds github_token:default
al creds add github_webhook_secret:myapp
al creds add git_ssh:prod

The <ref> format is type or type:instance. If no instance is specified, defaults to default. If the credential already exists, you’ll be prompted to update it.

`al creds rm <ref>`

Remove a credential from disk.

al creds rm github_token               # removes github_token:default
al creds rm github_webhook_secret:myapp

Removes all field files for the credential instance. If the type directory becomes empty, it is also removed.

`al run <agent>`

Manually triggers a single agent run. The agent runs once and the process exits when it completes. Useful for testing, debugging, or one-off runs without starting the full scheduler.

al run dev -p .
al run reviewer -p ./my-project
al run dev -c                 # Run on cloud

Option	Description
`-p, --project <dir>`	Project directory (default: `.`)
`-c, --cloud`	Run on cloud infrastructure

`al start`

Starts the scheduler. Runs all agents on their configured schedules and listens for webhooks.

al start -p .
al start -p ./my-project
al start -w                   # Enable web dashboard
al start -e                   # VPS deployment: expose gateway publicly

Option	Description
`-p, --project <dir>`	Project directory (default: `.`)
`-w, --web-ui`	Enable web dashboard (see Web Dashboard)
`-e, --expose`	Bind gateway to `0.0.0.0` (public) while keeping local-mode features
`-H, --headless`	Non-interactive mode (no TUI, no credential prompts)

`al stat`

Shows status of all discovered agents in the project.

al stat -p .
al stat -c                    # Show cloud status

Displays each agent’s schedule, credentials, and webhook configuration.

Option	Description
`-p, --project <dir>`	Project directory (default: `.`)
`-c, --cloud`	Show cloud infrastructure status

`al logs <agent>`

View log files for a specific agent.

al logs dev -p .
al logs dev -n 100          # Show last 100 entries
al logs dev -f              # Follow/tail mode
al logs dev -d 2025-01-15   # Specific date
al logs dev -c              # Cloud logs

Option	Description
`-p, --project <dir>`	Project directory (default: `.`)
`-n, --lines <N>`	Number of log entries (default: 50)
`-f, --follow`	Tail mode — watch for new entries
`-d, --date <YYYY-MM-DD>`	View a specific date’s log file
`-c, --cloud`	View cloud logs (Cloud Logging / CloudWatch)

`al pause [name]`

Pause the scheduler or a single agent. Without a name, pauses the entire scheduler — all cron jobs stop firing. With a name, pauses that agent — its cron job stops firing and webhook events are ignored. In-flight runs continue until they finish. Requires the gateway.

al pause                              # Pause the scheduler
al pause dev                          # Pause a single agent
al pause reviewer -p ./my-project
al pause dev -c                       # Pause via cloud gateway

Option	Description
`-p, --project <dir>`	Project directory (default: `.`)
`-c, --cloud`	Forward pause request to the cloud-deployed scheduler’s gateway

`al resume [name]`

Resume the scheduler or a single agent. Without a name, resumes the entire scheduler. With a name, resumes that agent — its cron job resumes firing and webhooks are accepted again.

al resume                             # Resume the scheduler
al resume dev                         # Resume a single agent
al resume reviewer -p ./my-project
al resume dev -c                      # Resume via cloud gateway

Option	Description
`-p, --project <dir>`	Project directory (default: `.`)
`-c, --cloud`	Forward resume request to the cloud-deployed scheduler’s gateway

`al kill <target>`

Kill an agent (all running instances) or a single instance by ID. Tries the target as an agent name first; if not found, falls back to instance ID. This does not pause the agent — if it has a schedule, a new run will start at the next cron tick. To fully stop an agent, pause it first, then kill.

al kill dev                           # Kill all instances of an agent
al kill my-agent-abc123               # Kill a single instance by ID
al kill dev -p ./my-project
al kill dev -c                        # Kill cloud tasks directly

Option	Description
`-p, --project <dir>`	Project directory (default: `.`)
`-c, --cloud`	Kill cloud tasks directly via ECS StopTask / Cloud Run cancel APIs

`al chat`

Open an interactive console. Without an agent name, opens the project-level console for creating and managing agents. With an agent name, opens an interactive session scoped to that agent’s environment — credentials are loaded and injected as environment variables (e.g. GITHUB_TOKEN, GIT_SSH_COMMAND), and the working directory is set to the agent’s directory.

al chat                # project-level console
al chat dev            # interactive session with dev agent's credentials
al chat dev -c         # same, but credentials from cloud secrets manager

Option	Description
`[agent]`	Agent name — loads its credentials and environment
`-p, --project <dir>`	Project directory (default: `.`)
`-c, --cloud`	Load credentials from cloud secrets manager

When running in agent mode, the command probes the gateway and warns if it is not reachable:

⚠ No gateway detected at http://localhost:8080. Resource locks, agent calls, and signals are unavailable.
  Start the scheduler with `al start -g` to enable these features.

The agent’s ACTIONS.md is loaded as reference context but is not auto-executed — you drive the session interactively.

Getting Started

Configuration

CLI

Features

Deployment

Examples

CLI Commands

CLI Commands

`al new <name>`

`al doctor`

`al creds ls`

`al creds add <ref>`

`al creds rm <ref>`

`al run <agent>`

`al start`

`al stat`

`al logs <agent>`

`al pause [name]`

`al resume [name]`

`al kill <target>`

`al chat`

Getting Started

Configuration

CLI

Features

Deployment

Examples

​CLI Commands

​al new <name>

​al doctor

​al creds ls

​al creds add <ref>

​al creds rm <ref>

​al run <agent>

​al start

​al stat

​al logs <agent>

​al pause [name]

​al resume [name]

​al kill <target>

​al chat

CLI Commands

`al new <name>`

`al doctor`

`al creds ls`

`al creds add <ref>`

`al creds rm <ref>`

`al run <agent>`

`al start`

`al stat`

`al logs <agent>`

`al pause [name]`

`al resume [name]`

`al kill <target>`

`al chat`