@ash-lang/cli

Ash is a task runner for AI agents — a scripting language that composes AI agents into automated workflows. Drop markdown files in a folder, number them, and run. When you need loops, retries, or conditional logic — add an .ash script. Start simple. Grow as needed.

Installation

npm

npm install -g @ash-lang/cli

On npm install, the correct platform binary is downloaded from GitHub Releases automatically.

Prebuilt binaries

Download from GitHub Releases.

Place the binary alongside ash.js in the npm package directory if the automatic download fails.

Requirements

• Rust 1.70+ (for building from source)
• Node.js (for npm install)

Quick Start

Configure your agent

Create ash.yml in your project root:

default_agent: opencode

Or set it per-run:

ash --agent opencode tasks/

Run your first project

my-project/
├── ash.yml
└── tasks/
    ├── 1-init/
    │   └── 01-setup.md
    └── 2-feature/
        └── 01-add-login.md

ash my-project/tasks/

Ash prints each task and its result as the agent completes it. Tasks that return a non-zero exit code are marked as failures.

Skip failures, keep going

ash --continue-on-error tasks/

Validate without running

ash --check tasks/

See what would run

ash --dry-run tasks/

Scripting with .ash Files

When you need more than one-shot prompts — chaining, conditionals, parallelism — write an .ash script:

#!opencode
do "Write a hello world program in Rust"
print stdout

ash hello.ash

Agent shebang

Declare the agent with a shebang:

#!opencode:1.0

do "Review src/" with opencode

Default agent

Set the default agent for all subsequent do calls with use:

use opencode
do "Review src/"                # uses opencode

use claude-code
do "Refactor the implementation" # uses claude-code

The agent can still be overridden per-call with do "..." with <agent>.

Language overview

use opencode                             # set default agent

do "Review src/"                         # call an agent

fn rollback(FILE) {                      # functions
  exec git restore "${FILE}"
  do "Summarize what has been done"
}

for FILE in FILES {                      # loops, conditionals, retry
  try {
    do "Fix bugs in ${FILE}"
  } fail {
    print "failed on ${FILE}"
  } upto 3
}

Supported Agents

| Agent | Description | |-------|-------------| | echo | Built-in passthrough for testing | | opencode | OpenCode CLI agent | | claude-code | Anthropic Claude Code | | aider | Aider AI pair programming |

Auto-discovery

Agents are auto-discovered on your PATH. Run to refresh:

ash discover

Custom agents

Add custom CLI-based agents in ash.yml:

agents:
  my-tool:
    type: local-cli
    cmd: my-tool
    message_flag: "--prompt"
    yes_flag: "--yes"

REPL

Run ash with no arguments to enter interactive mode:

$ ash
ash> NAME = "world"
ash> print "hello ${NAME}"
hello world

Commands: .help, .clear, .vars, .exit. Up/down arrows navigate history. Multi-line blocks (if, for, session) auto-detect continuation.