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

# Reference

> Global options, environment variables, files, shell completion and troubleshooting for the Famulor CLI

## Global options

These options work with every API command.

| Option | Purpose |
| - | - |
| `-o, --output json\|table\|jsonl` | Output format (default `json`) |
| `-i, --input <file\|->` | JSON request body from a file, or from stdin with `-` |
| `-F, --field key=value` | Set a body field; numbers, `true`/`false`, `null` and JSON are recognised |
| `-f, --raw-field key=value` | Set a body field as text |
| `--all` | Fetch every page of a list |
| `--columns a,b,c` | Columns for table output |
| `--output-file <path>` | Write the response to a file |
| `--dry-run` | Show the request without sending it |
| `-y, --yes` | Confirm deletes and other irreversible actions without a prompt |
| `-p, --profile <name>` | Use a saved login |
| `--base-url <domain>` | API host, for example your white-label domain |
| `--timeout <seconds>` | Deadline for the whole command, retries included |
| `-q, --quiet` | No progress output |
| `--debug` | Request and response details on stderr |
| `--no-color` | No colors or animation |
| `-h, --help` | Help for a command |

Run `famulor help options` for the same list in your terminal.

## CLI commands

| Command | Purpose |
| - | - |
| `famulor auth login` | Save an API key for a workspace (also `famulor login`) |
| `famulor auth status` | Show saved logins and check the active one |
| `famulor auth whoami` | Workspace, key name and scopes of the active login (also `famulor whoami`) |
| `famulor auth switch <profile>` | Change the default profile |
| `famulor auth logout` | Remove a saved key from this computer (also `famulor logout`) |
| `famulor commands [search]` | Search the API commands; `--full` adds every option |
| `famulor api <METHOD> <path>` | Send any API request |
| `famulor doctor` | Check the setup |
| `famulor completion bash\|zsh\|fish` | Shell completion |

## Environment variables

| Variable | Purpose |
| - | - |
| `FAMULOR_API_KEY` | API key; takes precedence over saved logins |
| `FAMULOR_BASE_URL` | API host, for example your white-label domain |
| `FAMULOR_PROFILE` | Saved login to use |
| `FAMULOR_OUTPUT` | Default output format |
| `FAMULOR_TIMEOUT` | Default deadline in seconds; `--timeout` wins |
| `FAMULOR_MAX_RETRIES` | Retries for rate limits and gateway errors, 0 to 10 (default 3) |
| `FAMULOR_CONFIG_DIR` | Where logins are saved |
| `FAMULOR_NO_KEYRING` | Save keys in an owner-only file instead of the system keychain |
| `FAMULOR_THEME` | `light` or `dark`, if colors are hard to read on your terminal background |
| `NO_COLOR` | Plain output without colors or animation |

## Files

Logins are saved in `~/.config/famulor` (on Windows in `%APPDATA%\famulor`). `config.json` holds the profiles and never the key itself. The key is kept in the system keychain, or in `credentials.json` with owner-only permissions where no keychain is available.

## Shell completion

```bash theme={null}
# zsh or bash: add to your shell profile
eval "$(famulor completion zsh)"

# fish
famulor completion fish > ~/.config/fish/completions/famulor.fish
```

Completion covers commands, area verbs, options, allowed values and saved profile names. The zsh script also works when `compinit` is not set up yet.

## Troubleshooting

Start with `famulor doctor`. It checks the Node.js version, the saved login, the host, the network connection and API Access.

| Message | What to do |
| - | - |
| `You are not logged in.` | Run `famulor auth login`, or set `FAMULOR_API_KEY`. |
| `403 api_access_required` | Your workspace plan does not include API Access. Add it under **Settings → Plan**. |
| `missing the required scope` | The key lacks that permission. Use a key with the scope. |
| `429 rate_limited` | The CLI retried where the API allowed it. Usage limits, such as a daily call limit, are not retried; the message names the limit. |
| `Refusing to … without confirmation` | Add `--yes` to delete or run an irreversible action from a script or coding agent. |

<Tip>
  Rate limits, the response format and error codes are the same as for the REST API. See the [API introduction](/api-reference/introduction) for details.
</Tip>