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

# ForceAI CLI

> Run the gateway and manage it from the command line with the forceai and forceai-proxy commands, plus the forceai Python SDK.

The ForceAI package ships two console commands and a Python SDK:

* **`forceai`** runs the gateway (the proxy server)
* **`forceai-proxy`** is the client you use to manage a running gateway and route traffic through it
* **`import forceai`** is the Python SDK for calling models in code

## Install

```bash theme={null}
pip install forceai
```

That installs both commands and the `forceai` package. To **run the gateway**
server you also need the proxy extra, which pulls in the server runtime:

```bash theme={null}
pip install 'forceai[proxy]'
```

> [!NOTE]
>
> The commands read their version from the package. In a release build
> `forceai --version` shows the ForceAI release (for example `v1.2.2`); a local
> checkout shows the engine version marked `(dev build)`.

## Run the gateway with `forceai`

`forceai` starts the proxy server against a config file. The config defines your
model list, guardrails and settings

```bash theme={null}
forceai --config config.yaml --port 4000 --detailed_debug
```

Common flags are `--host`, `--port`, `--num_workers`, `--detailed_debug` and
`--reload` (dev only). Run `forceai --help` for the full list. On startup it prints
the ForceAI banner and serves the API on the chosen port

## Use the client with `forceai-proxy`

`forceai-proxy` talks to a running gateway. Point it at the server with environment
variables, or pass `--base-url` and `--api-key` per command:

```bash theme={null}
export FORCEAI_PROXY_URL=https://your-gateway
export FORCEAI_PROXY_API_KEY=sk-your-forceai-key
```

> [!NOTE]
>
> In a split-plane deployment, management commands (keys, users, teams,
> credentials) are served by the **control plane**, while model and chat traffic
> goes to the **gateway**. Point `FORCEAI_PROXY_URL` at the control plane for
> management and at the gateway for model calls, or at the single origin if your
> deployment fronts both behind one URL. The legacy `LITELLM_PROXY_URL` /
> `LITELLM_PROXY_API_KEY` names are still accepted as a fallback.

### Everyday commands

```bash Models and raw requests theme={null}
forceai-proxy models list                     # models the gateway serves
forceai-proxy http request GET /v1/models      # raw HTTP to the proxy
```

```bash Management theme={null}
forceai-proxy keys list                         # API keys
forceai-proxy users --help                      # manage users
forceai-proxy teams --help                       # manage teams and assignments
forceai-proxy credentials --help                 # reusable provider credentials
```

```bash Auth and chat theme={null}
forceai-proxy login                              # SSO sign-in to the proxy
forceai-proxy whoami                             # current auth status
forceai-proxy chat gpt-4o-mini                   # interactive streaming chat
```

```bash Maintenance theme={null}
forceai-proxy encryption migrate --check         # at-rest credential migration
forceai-proxy version                             # CLI and server version
```

`--help` works at every level, so `forceai-proxy keys --help` or
`forceai-proxy models list --help` show the exact options for any command

### Route coding tools through the gateway

`forceai-proxy` can launch a coding tool already wired to your gateway, so every
call it makes is governed:

```bash theme={null}
forceai-proxy claude      # Claude Code through the gateway
forceai-proxy codex       # Codex
forceai-proxy opencode    # OpenCode
```

It logs in if needed, verifies your key against the proxy, exports the env the
tool reads, then hands off. Arguments after the tool name are forwarded to it. For
pinning models and the full Claude Code setup, see [Connect Claude Code](https://gateway.forceaisecurity.com/coding/claude-code.md)

## The Python SDK

`import forceai` gives the model-calling SDK. It mirrors the engine surface, so
`forceai.completion` and `forceai.acompletion` work the same way, and ForceAI's
own feature subpackages (`forceai.guardrails`, `forceai.audit`, and so on) are
importable alongside it:

```python theme={null}
import forceai

resp = forceai.completion(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "say hi"}],
)
print(resp.choices[0].message.content)
```

To route the SDK through a running gateway instead of calling providers directly,
point it at the gateway and use a ForceAI key:

```python theme={null}
import forceai

resp = forceai.completion(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "say hi"}],
    api_base="https://your-gateway",
    api_key="sk-your-forceai-key",
)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.