# tf-cli

`tf-cli` provides the `tf` command to store TokenFlux API keys, select models, and launch Claude Code, Codex, OpenCode, or Pi. It is not a standalone chat client; the launched client handles conversations.

Use `tf` to manage multiple keys from the terminal or preserve your clients' existing global configurations. For graphical provider configuration, see [CC-Switch](https://docs.tokenflux.dev/en/docs/agents/cc-switch.md).

## Installation

Choose one installation method.

<DocsTabs default-tab="npm">
  <DocsTab title="npm" name="npm">

Requires Node.js 18 or later:

```bash
npm install -g @tokenflux/tf
```

The official npm package is **`@tokenflux/tf`**. The unscoped `tf` and `tf-cli` packages are unrelated projects. Platform binaries are distributed through optional dependencies; do not use `--omit=optional` or `--no-optional`.

  </DocsTab>
  <DocsTab title="macOS / Linux" name="unix">

```bash
curl -fsSL https://raw.githubusercontent.com/tokenflux/tf-cli/main/install.sh | sh
```

Installs to `~/.local/bin/tf` by default without administrator privileges. The script does not modify the system PATH. If the terminal cannot find `tf`, follow the installation instructions to add that directory, or run this for the current session:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

  </DocsTab>
  <DocsTab title="Windows" name="windows">

Run in PowerShell 5.1 or PowerShell 7:

```powershell
irm https://raw.githubusercontent.com/tokenflux/tf-cli/main/install.ps1 | iex
```

Installs to `%USERPROFILE%\.local\bin\tf.exe` by default without administrator privileges. Follow the installation instructions to add the directory to PATH. The installation script itself does not require Git Bash.

Native Windows interaction requires tf-cli 0.9.0 or later; Windows Terminal is recommended. Launching clients installed through npm / pnpm still requires Git Bash on PATH.

  </DocsTab>
</DocsTabs>

Check that the command is available:

```bash
tf version
tf --help
```

## Import a TokenFlux API Key

Prepare a key using [Create API Key](https://docs.tokenflux.dev/en/docs/tokenflux/create-apikey.md). Confirm that its group allows the target client and protocol, and that the account has available inference credits.

```bash
tf login
```

1. Choose "Import from web", then select the default TokenFlux gateway.
2. Use the Keys page opened by the terminal, select the key, and complete the web import operation.
3. Return to the terminal, check the origin, gateway, group, and masked key, then confirm to save.
4. If you did not specify a local name, choose automatic naming, the web key name, or a custom name when prompted.

**Do not share the full web link opened by the terminal.** It contains verification information for this import session. If the page or terminal reports an unverified session, cancel and reopen the link generated by `tf login`. The key is saved only after you confirm in the terminal.

If your browser fails to open automatically, use hidden input instead:

```bash
tf login --with-key
```

Select the TokenFlux gateway and paste the key when prompted. Do not pass a real key as a command-line argument.

To assign a fixed local name, such as `work`:

```bash
tf login work
```

`work` is a local alias, not a platform group name. Replacing a different key under an existing name requires confirmation and defaults to cancellation.

## Launch a Client

Run the command for your client:

| Client                                     | Launch command |
| ------------------------------------------ | -------------- |
| [Claude Code](https://docs.tokenflux.dev/en/docs/agents/claude-code.md) | `tf claude`    |
| [Codex](https://docs.tokenflux.dev/en/docs/agents/codex.md)             | `tf codex`     |
| [OpenCode](https://docs.tokenflux.dev/en/docs/agents/opencode.md)       | `tf opencode`  |
| [Pi](https://docs.tokenflux.dev/en/docs/agents/pi.md)                   | `tf pi`        |

On first launch, follow the prompts to choose a key, main model, and required auxiliary models. Default bindings and model settings are saved in `tf`'s own configuration. If the client is not installed, interactive mode offers installation options and installs only after confirmation.

In the client, start a new conversation and send "Reply with OK only". **This makes a real model call and incurs charges.** After receiving a text response, check the key, model, and charge in the [usage logs](https://tokenflux.dev/usage). Successful installation, key import, or listing models alone does not prove that inference works.

## Temporary Overrides and Default Models

### For This Launch Only

```bash
tf claude -m
tf codex -k work
tf codex -e high
```

`-m` without a value opens the model picker; `-k work` selects a locally stored key; `-e high` sets reasoning effort for this launch, subject to model and client support. These flags do not change saved default bindings or slots.

Put underlying client arguments after `--`, for example to resume a Claude Code session:

```bash
tf claude -- --resume
```

`tf codex --help` shows Codex's own help. Use `tf --help codex` for the `tf` wrapper's options.

### Change Models for Future Launches

Inspect the Codex model assignment or open its editor:

```bash
tf model codex
tf model codex --edit
```

Model slots assign models to different tasks in a client:

| Client      | Model slots                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| Claude Code | `default` main conversation, `fast` background tasks, `heavy` high-compute tier |
| Codex       | `default` main conversation, `review` code review                               |
| OpenCode    | `default` main model, `small` lightweight tasks                                 |
| Pi          | `default` main conversation                                                     |

You can also set a slot directly. Replace `MODEL_ID` with a full model ID supported by the current key; preserve the group prefix for a [composite key](https://docs.tokenflux.dev/en/docs/tokenflux/composite-key.md):

```bash
tf model codex --set default=MODEL_ID
```

Changing keys affects the availability of selected models. Before clearing affected slots, the editor lists the changes and asks for confirmation.

## Configuration Boundaries and Credential Storage

`tf` injects gateway configuration through child-process environments and launch arguments without rewriting clients' global configuration files. Running `codex`, `claude`, or another client directly does not use the `tf` binding. Clients can still save their own sessions or settings; `tf` does not sandbox them.

Run `tf config` to locate configuration and credentials. The default configuration directory is `~/.tf`; when using XDG paths, follow the actual command output. API keys are stored in plaintext in `credentials.json`, protected by `0600` permissions on Unix or an access control list on Windows. This is not encryption at rest. Do not publish or sync that file.

If other configuration tools have already written settings, run `tf status` to inspect conflicts. For example, `env` in `~/.claude/settings.json` can override process injection. Back up the file and inspect the reported fields instead of deleting the entire configuration.

## Troubleshooting and Removing Keys

```bash
tf status
tf keys
tf keys --refresh
```

`tf status` shows saved accounts' usage, model bindings, and environment conflicts. `tf keys` lists local keys and their eligible clients. After group or model changes, use `tf keys --refresh` to refresh the catalog and protocol probes.

If candidate models are hidden, check the protocol or client restrictions reported in the terminal. `tf` does not bypass group restrictions; switch to a group that supports your target client rather than merely changing the Base URL. For actual request errors, see [Troubleshooting](https://docs.tokenflux.dev/en/docs/troubleshooting.md).

Remove the locally stored `work` key:

```bash
tf logout work
```

This does not revoke the key on TokenFlux. If it has leaked, also disable the old key on the [API keys page](https://tokenflux.dev/keys).

## Updating and Uninstalling

For npm installations, update with npm:

```bash
npm install -g @tokenflux/tf@latest
```

When no longer needed, uninstall the npm package:

```bash
npm uninstall -g @tokenflux/tf
```

Standalone binary installations can check with `tf update --check` and upgrade with `tf update`. For script-based uninstallation, see the [project README](https://github.com/tokenflux/tf-cli#readme). Uninstalling preserves local credentials and configuration by default; confirm whether you still need them before removing them.

## Related Pages

- [tf-cli project and releases](https://github.com/tokenflux/tf-cli/releases)
- [Credential security](https://github.com/tokenflux/tf-cli/blob/main/SECURITY.md)
- [Report a tf-cli issue](https://github.com/tokenflux/tf-cli/issues)