DEEN

DocsAutomate

Headless and CI

alran exec runs one task without the TUI: in scripts, in CI, in batch jobs.

How do I run a task without the terminal UI?

bash
alran exec "Add a test for the date parser and make it pass"

It prints the final answer and exits. The exit code tells your script whether it worked.

Read the result in code

bash
alran exec --output-format json "List the TODO comments in src/"
alran exec --output-format stream-json "Fix the lint errors" | jq .
alran exec -o summary.md "Summarize what changed since the last tag"

--output-schema takes a JSON Schema (a file or inline) the final answer must match, so you get data, not prose:

bash
alran exec --output-schema schema.json --output-format json "Rate each open issue by effort"

Options

OptionWhat it does
--cwd <path>The workspace folder
--file <path>Attach a file (repeatable)
--input -Read the prompt from stdin; --input-format json for structured input
--model <provider/model>Another model for this run
--effort <level>Reasoning effort for this run
--permission <policy>smart (default), full or off
--timeout <duration>Stop after, for example, 30s or 2m
--max-steps <count>Stop after this many assistant steps
--session <id> / --continueRun inside an existing session
--mode lightweightNo tools, no files: a quick answer
--prompt-mode <mode>tui (default), coding or work
--diagnostics-dir <path>Save bounded diagnostics for a failed run

In CI

Create an API key at ai.ottili.one/api-keys, store it as a secret and pass it as ALRAN_API_KEY:

yaml
# .github/workflows/alran.yml
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - run: npm install -g alran
      - run: alran exec --permission smart --timeout 10m "Review this change and list risky spots"
        env:
          ALRAN_API_KEY: ${{ secrets.ALRAN_API_KEY }}

alran exec review reviews staged, unstaged and untracked local changes.

Exit codes

CodeMeaning
0The run finished successfully
2The command line was wrong: a missing prompt, an unknown flag or an unusable model
3The configuration is broken — open Alran and run /doctor
4The run started, but the model or the runtime failed
6The run hit --timeout
7The run hit --max-steps
70An internal error — please report it
130The run was cancelled
141The output pipe was closed early

Account commands (alran auth, alran config, alran models, alran usage, alran billing) use their own set: there 2 means sign-in needed, 4 means the Platform is unreachable and 5 means your credit does not cover the request, or Claude has no working Anthropic key. Both lists stand on Error codes.

Common questions

How do I run Alran Code in CI?

Create an API key on the Ottili AI Platform, store it as a secret and pass it as ALRAN_API_KEY. Then call alran exec in your workflow, for example alran exec --permission smart --timeout 10m to review a change and list risky spots. The exit code tells your script whether the run worked.

How do I get JSON instead of prose from alran exec?

Use alran exec --output-format json for one JSON document, or --output-format stream-json for one JSON event per line, which you can pipe into jq. If the answer has to match a fixed shape, pass a JSON Schema with --output-schema, and write the result to a file with -o.

What do the exit codes of alran exec mean?

Zero means the run finished successfully, 2 means the command line was wrong, 3 means the configuration is broken, 4 means the model or the runtime failed, 6 means the run hit --timeout, 7 means it hit --max-steps, 70 is an internal error, 130 means the run was cancelled and 141 means the output pipe was closed early. The account commands alran auth, alran config, alran models, alran usage and alran billing use their own set of codes, and the Error codes page lists both.