---
title: "Headless and CI · Alran Code Docs"
url: https://alran.dev/en/docs/headless
locale: en
updated: 2026-11-16
---

[Docs](https://alran.dev/en/docs)Automate

# Headless and CI

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

On this page

[How do I run a task without the terminal UI?](#run) [Read the result in code](#output) [Options](#options) [In CI](#ci) [Exit codes](#exit) [Common questions](#faq)

## How do I run a task without the terminal UI? {#run}

```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 {#output}

```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 {#options}

| Option | What 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>` / `--continue` | Run inside an existing session |
| `--mode lightweight` | No 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 {#ci}

Create an API key at [ai.ottili.one/api-keys](https://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 {#exit}

| Code | Meaning |
| `0` | The run finished successfully |
| `2` | The command line was wrong: a missing prompt, an unknown flag or an unusable model |
| `3` | The configuration is broken — open Alran and run `/doctor` |
| `4` | The run started, but the model or the runtime failed |
| `6` | The run hit `--timeout` |
| `7` | The run hit `--max-steps` |
| `70` | An internal error — please report it |
| `130` | The run was cancelled |
| `141` | The 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](https://alran.dev/en/docs/errors).

## Common questions {#faq}

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.

[PreviousMCP servers](https://alran.dev/en/docs/mcp) [NextNode.js and ACP](https://alran.dev/en/docs/sdk)
