> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Scripts, CI and coding agents

> Automate Famulor safely: clean output, exit codes, confirmations, dry runs and a command schema for agents

The CLI is built to be scripted. Data goes to stdout, messages go to stderr, and every failure ends with a non-zero exit code.

## Safe by default

* **Deletes and irreversible actions ask first.** This covers deletes and actions such as buying a number, transferring a workspace or restoring an old version. On a terminal the CLI asks for confirmation. In scripts, CI and coding agents, pass `--yes`; without it the command refuses to run.
* **Dry runs.** `--dry-run` prints the exact request (method, URL, headers and body) with the API key hidden, and sends nothing.
* **Retries that cannot double-book.** When the rate limit is reached, the CLI waits for the time the API asks for and tries again. Requests that create something are never repeated after a timeout or a usage limit, so a call is never placed twice. `--timeout` is the deadline for the whole command, waiting included.
* **No prompts without a person.** In CI and inside coding agents the CLI never waits for input.

```bash theme={null}
famulor delete-assistant <id> --yes
famulor create-call --assistant-id <id> --to-number +4930123456 --dry-run
```

## Examples

```bash theme={null}
# Names of all assistants
famulor list-assistants --all --output jsonl | jq -r '.name'

# Turn on recording for every assistant
famulor list-assistants --all --output jsonl | jq -r '.id' \
  | xargs -I{} famulor update-assistant {} --recording-enabled true

# Save every completed call
famulor list-calls --status completed --all > calls.json
```

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Success |
| `1` | API or network error |
| `2` | Usage error, such as an unknown option or invalid value |
| `3` | Not logged in, or the API rejected the credential or permission |
| `4` | Not found |
| `5` | Cancelled at a confirmation prompt |

## Errors in scripts

When a command fails, stdout stays empty, so a failure is never read as data. When stderr is not a terminal, its last line is the error as JSON (warnings, if any, come before it):

```json theme={null}
{"error":{"code":"not_found","message":"Not found (404 not_found): Call not found.","status":404,"exit_code":4}}
```

`code` is the API's error code. Failures without an API answer use `network_error`, `timeout`, `invalid_response`, `usage_error` or `auth_error`. `retry_after` gives the seconds to wait after a rate limit. `may_have_executed: true` means a request that creates something may have reached the API before the connection failed, so check before you retry.

```bash theme={null}
famulor get-call <id> > call.json 2> error.log || tail -n 1 error.log | jq -r '.error.code'
```

## GitHub Actions

```yaml theme={null}
- uses: actions/setup-node@v4
  with:
    node-version: 22
- run: npm install --global famulor
- run: famulor list-calls --status failed --limit 50 --output jsonl
  env:
    FAMULOR_API_KEY: ${{ secrets.FAMULOR_API_KEY }}
```

## Coding agents

Coding agents such as Claude Code, Codex and Cursor can use the CLI directly:

* `famulor commands <topic>` finds commands. Outside a terminal it prints compact JSON: command, summary, method, path and area.
* `famulor <command> --help --output json` prints one command's full schema: arguments, options, types, allowed values, defaults, limits, required fields and an example. `famulor commands --full --output json` does this for every command.
* Colors, animations and prompts switch off automatically in CI and inside coding agents. Irreversible actions need `--yes`.
* Error messages say what went wrong and what to run next.

A short instruction is usually enough, for example: "Use the `famulor` CLI. Find commands with `famulor commands <topic>` and read one with `famulor <command> --help --output json`. Try writes with `--dry-run` first."

<Tip>
  For conversational work inside an AI assistant, the [MCP server](/mcp/overview) is the better fit. It offers the same capabilities as tools.
</Tip>