# Python CLI reference

<!-- Generated by scripts/generate_python_cli_docs.py. Edit the parser help, not this file. -->

Generated from the CLI source in this checkout (package version **0.7.0**). Use `agentic-api --help` or `agentic-api <command> --help` for your installed version.

Agentic API provides two command-line interfaces (CLIs), both used from a terminal. The PyPI package includes both:

- **Python launcher: `agentic-api ...`** — start the gateway with `agentic-api serve`, check your installation with `agentic-api doctor`, or inspect versions with `agentic-api version`. You can also use `python -m agentic_api ...`. This page documents the Python launcher.
- **[Rust CLI](rust-cli.md): `agentic ...`** — run harnesses with `agentic run codex` or `agentic run claude`, or use `agentic serve` and `agentic validate`. It has its own commands and flags; run `agentic --help` for its command-line reference.

See [Python installation and workflows](../guides/python-installation.md) for package installation, remote and local serving examples, and diagnostics.

## agentic-api

```text
usage: agentic-api [-h] [--version] {serve,doctor,version} ...

Python launcher for packaged Agentic API binaries

positional arguments:
  {serve,doctor,version}
    serve               Launch Agentic API in local or remote mode
    doctor              Report packaged binary and compatibility diagnostics
    version             Print package and packaged binary versions

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
```

## agentic-api serve

```text
usage: agentic-api serve [-h] [--model MODEL] [--vllm-base-url VLLM_BASE_URL]
                         [--host HOST] [--port PORT]
                         [--startup-timeout-s STARTUP_TIMEOUT_S]
                         [--shutdown-timeout-s SHUTDOWN_TIMEOUT_S]
                         [--vllm-port VLLM_PORT]
                         [--gateway-api-key-env GATEWAY_API_KEY_ENV]
                         [--vllm-api-key-env VLLM_API_KEY_ENV]
                         ...

Launch the packaged Rust gateway. Choose exactly one of --model (managed local vLLM) or
--vllm-base-url (an existing upstream server).

positional arguments:
  vllm_args             Extra local vLLM arguments after --

options:
  -h, --help            show this help message and exit
  --model MODEL         Model to serve with managed local vLLM; requires a local vLLM
                        install (default: None)
  --vllm-base-url VLLM_BASE_URL
                        HTTP(S) base URL of an existing upstream, without credentials
                        (default: None)
  --host HOST           Gateway listen address (default: 0.0.0.0)
  --port PORT           Gateway listen port (default: 9000)
  --startup-timeout-s STARTUP_TIMEOUT_S
                        Startup readiness timeout in seconds (default: 600.0)
  --shutdown-timeout-s SHUTDOWN_TIMEOUT_S
                        Grace period in seconds before terminating child processes
                        forcibly (default: 10.0)
  --vllm-port VLLM_PORT
                        Managed local vLLM listen port (default: 8000)
  --gateway-api-key-env GATEWAY_API_KEY_ENV
                        Environment variable containing the upstream API key used by the
                        gateway (default: OPENAI_API_KEY)
  --vllm-api-key-env VLLM_API_KEY_ENV
                        Environment variable containing the managed local vLLM API key;
                        also passed to the gateway (default: AGENTIC_VLLM_API_KEY)

Pass extra vLLM arguments after -- in local mode. The launcher reserves --host, --port,
and --api-key; --uds is incompatible. Ports must be 1-65535. Timeouts must be greater
than 0 and at most 86400 seconds.
```

## agentic-api doctor

```text
usage: agentic-api doctor [-h] [--mode {local,remote}] [--json]

Check the packaged gateway and local vLLM compatibility. Without --mode, report both
modes and use remote health for the exit status. Exit 0 when healthy, 1 otherwise.

options:
  -h, --help            show this help message and exit
  --mode {local,remote}
                        Select which mode to check (default: None)
  --json                Emit a machine-readable JSON report (default: False)
```

## agentic-api version

```text
usage: agentic-api version [-h]

Print the Python package, packaged Rust binary, and supported and installed vLLM
versions. Use agentic-api --version to print only the Python package version.

options:
  -h, --help  show this help message and exit
```