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.

Installation

Choose one installation method.

Requires Node.js 18 or later:

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.

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:

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

Run in PowerShell 5.1 or PowerShell 7:

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.

Check that the command is available:

tf version
tf --help

Import a TokenFlux API Key

Prepare a key using Create API Key. Confirm that its group allows the target client and protocol, and that the account has available inference credits.

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:

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:

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	tf claude
Codex	tf codex
OpenCode	tf opencode
Pi	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. Successful installation, key import, or listing models alone does not prove that inference works.

Temporary Overrides and Default Models

For This Launch Only

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:

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:

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:

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

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.

Remove the locally stored work key:

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.

Updating and Uninstalling

For npm installations, update with npm:

npm install -g @tokenflux/tf@latest

When no longer needed, uninstall the npm package:

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. Uninstalling preserves local credentials and configuration by default; confirm whether you still need them before removing them.

Related Pages

• tf-cli project and releases
• Credential security
• Report a tf-cli issue