Famulor CLI: Safely Manage Your Workspace in the Terminal

Many teams start in the user interface: they create assistants, review calls, and adjust campaigns manually. Once the same steps need to be repeated across workspaces, checked in a pipeline, or executed by a coding agent, teams need a reproducible interface. That is the purpose of the Famulor CLI, the official command-line tool released as a public preview on October 1, 2026.

According to the Famulor changelog for October 1, 2026, the CLI exposes every public REST API operation as a terminal command. It can manage assistants, calls, campaigns, leads, phone numbers, and call history. This guide covers setup, a controlled automation workflow, and the limits you need to understand before production use.

Key points

• The Famulor CLI is a public preview at version 0.x. Command names may change before version 1.0.
• It requires Node.js 22 or newer, a workspace plan with API Access, and an API key from Settings → API & MCP.
• Interactive logins use the system keychain where available. In CI, FAMULOR_API_KEY is read from the secret store without the CLI saving it.
• JSON, table, and JSON Lines output separate human review from machine processing.
• --dry-run, explicit confirmations, exit codes, and structured errors support safer workflows. They do not replace permissions, approval, or data-protection rules.

The content gap: CLI is not the same as API or MCP

Famulor already explains the MCP server for AI agents and a Famulor.io skill for API actions. Both approaches connect AI systems to the platform, but the CLI solves a different problem.

The CLI does not replace these options. It adds a documented command-line layer over the REST API. Teams can export data, validate state, or build a small automation without first writing an API client. The REST API remains the right foundation for a full product integration; for conversational work inside an AI client, the CLI documentation points to MCP.

Who should use the Famulor CLI?

The new interface is particularly relevant for teams that need controlled, repeatable operations:

• Agencies and white-label providers managing several workspaces through separate profiles
• Voice AI and operations teams regularly checking assistants, campaigns, or failed calls
• Developers exploring API behavior in the terminal before moving it into application code
• DevOps and QA teams reading, validating, or documenting state in CI
• Coding-agent users who need machine-readable command discovery and parameter schemas

The benefit is not an automatic amount of time or money saved. The defensible advantage is reproducibility: a documented command can be reviewed, repeated with the same parameters, and evaluated through its exit code.

Requirements and installation

The official CLI overview lists three requirements:

1. Node.js 22 or newer
2. a Famulor workspace plan with API Access
3. an API key from Settings → API & MCP

Install the package globally and check the environment:

npm install --global famulor
famulor doctor

The reference says famulor doctor checks the Node.js version, saved login, host, network connection, and API Access. Because the CLI is currently a public preview, plan updates deliberately and do not build production pipelines around undocumented assumptions. Running the install command with @latest updates the tool.

Interactive login

Create a key with the required scopes in the Famulor dashboard, then run:

famulor auth login
famulor auth whoami
famulor list-assistants --output table

The input stays hidden. Under the documented authentication flow, the key is checked against the API before it is saved. The CLI uses Keychain on macOS, Credential Manager on Windows, and a Secret Service such as GNOME Keyring or KWallet on Linux. If no keychain is available, it reports an owner-only fallback file under ~/.config/famulor.

This storage is a technical control, not an authorization strategy. Create separate keys for separate purposes, grant only the required scopes, and revoke a key in the dashboard when it is no longer needed. famulor auth logout removes only the local copy.

Keep multiple workspaces separate

An API key belongs to exactly one workspace. Agencies should therefore save one profile per workspace rather than swapping keys inside scripts:

famulor auth login --profile client-a
famulor auth login --profile client-b
famulor auth status

famulor list-assistants --profile client-a --output table

famulor auth switch client-a makes a profile the default, while --profile overrides it for one call. FAMULOR_PROFILE applies to an entire shell session. White-label operators can also save their domain with --base-url during login.

A profile is not tenant approval. Before write commands, use famulor auth whoami to confirm the active workspace, key name, and scopes. That short check helps prevent changes to the wrong workspace when assistants have similar names.

Discover commands without memorizing the API

The CLI converts the API operation ID to kebab case. The createCall API operation becomes famulor create-call. The commands and output documentation offers several discovery paths:

famulor --help
famulor calls
famulor commands recording
famulor get-call-recording --help

API path parameters become arguments; query and body fields become options. The CLI checks types, allowed values, and required fields before sending a request. Complex request bodies can come from JSON files or stdin, and text values beginning with @ can be read from a file.

famulor create-assistant --input assistant.json --dry-run
famulor update-assistant <assistant-id> --name "Front desk" --dry-run
famulor list-calls --status completed --limit 20 --output table

A dry run sends nothing. It shows the method, URL, headers, and body while hiding the API key. The body may still contain personal or confidential content, so review it before copying the output into a ticket or log.

Output for people and automation

The Famulor CLI supports three documented formats:

--all follows pagination. With JSONL, records are printed as each page arrives. Progress and messages go to stderr while data stays on stdout, so pipelines do not misread status messages as records.

famulor list-assistants --all --output jsonl \
  | jq -r '.id + "\t" + .name'

Use large exports intentionally. --all can return substantially more personal or operational data than one page. Store exports only where retention, access, and deletion are governed.

Four stages for safer writes

A robust CLI workflow separates reading, reviewing, writing, and verification.

1. Read the context

Check the profile, resource, and current state. Use IDs rather than display names alone when duplicate names are possible.

2. Preview the request

Add --dry-run to supported API commands. Record the expected change in a review, never the secret key.

3. Approve the change deliberately

Deletes and other irreversible actions require confirmation. In CI and coding-agent contexts, the CLI refuses to proceed without --yes instead of waiting for input, according to the scripting documentation. Use --yes only after your own approval condition, not as a blanket option.

4. Read the resulting state

Verify through a GET or list command. After a timeout, a create request may already have reached the API. A structured error can then include may_have_executed: true. Query the target state before repeating the same create command.

These four stages matter more than producing the shortest shell script. They reduce context mistakes, make approval visible, and avoid blind retries after ambiguous network failures.

CI: keep secrets out of scripts

In noninteractive environments, the CLI reads FAMULOR_API_KEY from the secret store. The variable takes precedence over saved logins, and the CLI does not write that key to disk.

- 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 }}

This read-only example follows the Famulor documentation. For writes, add separate environments, restricted scopes, protected branches, and an approval step. A secret store does not prevent an overly broad key from having an overly broad impact.

Use coding agents with explicit boundaries

The CLI can expose its command schema in machine-readable form:

famulor commands assistant
famulor update-assistant --help --output json
famulor commands --full --output json

Outside a terminal, command search returns compact JSON with command, summary, method, path, and area. Help output describes arguments, types, allowed values, limits, and required fields. A coding agent can discover and inspect before constructing a command.

A useful agent instruction still narrows the action space:

Use the Famulor CLI. First read the active profile and current assistant. Discover commands with famulor commands. Run every write with --dry-run first. Do not perform an irreversible action and do not use --yes.

The CLI switches off colors, animation, and interactive prompts in CI and coding agents. That makes it machine-friendly, not self-authorizing. The operating team remains responsible for scope, review, and permitted actions.

Practical example: QA across client workspaces

A Voice AI agency operates separate Famulor workspaces. Every morning, an internal QA job should list failed calls since the previous review. A team member then decides whether an assistant needs a change.

A realistic workflow:

1. Each workspace has its own profile or CI secret with read scopes.
2. The job calls list-calls with a status filter and structured output.
3. Results are processed in an access-controlled QA environment, not copied blindly into public logs.
4. A team member reviews relevant conversation data in Famulor and assesses the cause and necessary change.
5. A proposed assistant update is generated as a --dry-run and reviewed.
6. After approval, the real update runs with a separate, appropriately scoped key.
7. The pipeline reads the assistant again and records the resulting state.

This is an illustrative workflow, not a measured customer outcome. It separates observation, professional judgment, and technical modification. The repeatable transport is automated while the quality decision remains reviewable.

Errors, exit codes, and retries

Scripts should not search for fragments of human-readable text. The CLI documents fixed exit codes: 0 for success, 1 for API or network errors, 2 for usage errors, 3 for login or authorization, 4 for not found, and 5 for a cancelled confirmation.

When stderr is not a terminal, stdout stays empty on failure and the final stderr line contains a JSON error. Pipelines can inspect the error code, HTTP status, and, where present, retry_after or may_have_executed.

Rate limits are retried within the documented rules. Create requests are not automatically repeated after a timeout or usage limit, specifically to prevent an action such as placing the same call twice. Your pipeline must preserve that distinction.

Telephony, recordings, and data protection

The CLI does not change the rules of the underlying workspace. If a command starts a call, downloads a recording, or exports conversation data, your telephony, consent, retention, and access rules still apply.

• Test outbound calls only with permitted target numbers, times, and consent basis.
• Treat transcripts, recordings, phone numbers, and lead data as personal or confidential data where applicable.
• Never place API keys in repositories, shell history, dry-run artifacts, or chat transcripts.
• Restrict scopes and separate read-only QA jobs from production writes.
• Apply appropriate retention and deletion rules to logs and exports.

Keychain storage, preview safeguards, or EU operations do not create a blanket compliance guarantee for your process. The legal and organizational assessment depends on the use case.

Test matrix before production

Run these tests first in a limited workspace with non-production resources. Valid syntax only proves that a request is structurally acceptable; it does not prove that the business change is appropriate.

Frequently asked questions

Is the Famulor CLI stable for production pipelines?

It launched on October 1, 2026 as a public preview at version 0.x. Command names may change before 1.0; a renamed command remains functional for at least one minor version according to the documentation. Review and version updates deliberately.

Do I need a new API key?

The CLI uses the same workspace API keys as the REST API. A separate key with only the required scopes is still sensible for a narrowly defined workflow.

Can I use the CLI for several client workspaces?

Yes. Store one profile per workspace. Switch deliberately through auth switch, --profile, or FAMULOR_PROFILE, and confirm the context with auth whoami before writes.

Which is better for an AI client: CLI or MCP?

For conversational work in a supported AI client, Famulor recommends MCP. The CLI is a better fit for shell scripts, CI, and coding agents that need deterministic commands and structured output.

Does --dry-run prevent every misconfiguration?

No. It sends nothing and makes the technical request reviewable. You must still verify the target workspace, data, permissions, and business intent.

Conclusion: automate the workflow, not responsibility

The Famulor CLI closes the gap between visual administration and a custom API client. Profiles, typed options, structured output, dry runs, exit codes, and machine-readable help provide a strong foundation for repeatable operations and development workflows.

Start read-only, restrict scopes, and make every write reviewable: read context, inspect the dry run, approve deliberately, and verify the resulting state. That makes the command line not only fast, but controllable.

About the author

Sarah Müller writes about Voice AI products, integrations, and the safe adoption of automated customer workflows at Famulor.