Scripts, CI and coding 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.

famulor delete-assistant <id> --yes
famulor create-call --assistant-id <id> --to-number +4930123456 --dry-run

Examples

# 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):

{"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.

famulor get-call <id> > call.json 2> error.log || tail -n 1 error.log | jq -r '.error.code'

GitHub Actions

- 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.”

For conversational work inside an AI assistant, the MCP server is the better fit. It offers the same capabilities as tools.

​Safe by default

​Examples

​Exit codes

​Errors in scripts

​GitHub Actions

​Coding agents

Safe by default

Examples

Exit codes

Errors in scripts

GitHub Actions

Coding agents