OpenRouter Control

OpenRouter Control is a Python CLI for creating and managing OpenRouter API keys. The tool stores a provisioning key locally and offers commands to view usage, audit remaining budgets and adjust limits.

⚠️ Disclaimer: This tool is not affiliated with, endorsed by, or created by OpenRouter. It is an independent tool designed to work with OpenRouter's API. OpenRouter is a trademark of its respective owners.

Author: McGroarty
Repository: https://github.com/mcgroarty/openrouter-control
License: Apache 2.0

Features

• Compact and detailed usage views
• Create and delete API keys
• Adjust per-key spending limits (set, set-min, set-max, add)
• Audit keys approaching their limits with optional thresholds
• Configuration stored securely in a user specific directory

Installation

1. Ensure Python 3.6+ is available

2. Install dependencies

   pip install -r requirements.txt

3. Run the script

   ./openrouter-control

   The first run prompts for your provisioning key and saves it to openrouter-control.json in a platform specific directory. You can also set the OPENROUTER_PROVISIONING_KEY environment variable to supply the key non-interactively or avoid storing it on disk.

Platform Support

This tool is cross-platform and has been tested on:

• Linux/macOS: Full Unix-style permissions and diagnostics
• Windows: Windows-specific troubleshooting features

The tool automatically detects your operating system and adapts accordingly.

Command Overview

Command	Description	CSV/JSON Export
usage	Show a table of API keys with usage and remaining budget (default)	✓
info	Display detailed account and key information
audit [AMOUNT] [PERCENT]	List keys with limits sorted by remaining amount. Optional dollar and/or percent thresholds act as OR filters.	✓
create NAME AMOUNT	Create a new API key with the given name and budget
delete HASH	Delete an API key by 8 character hash prefix
set-min AMOUNT	Increase limits so remaining budget is at least AMOUNT	✓
set-max AMOUNT	Reduce limits to keep remaining budget under AMOUNT	✓
set AMOUNT	Set remaining budget exactly to AMOUNT	✓
add AMOUNT	Add AMOUNT to the current remaining budget	✓
config-path	Print the path of the configuration file
debuginfo	Show diagnostic information for troubleshooting
reset	Remove the stored provisioning key
--version	Show tool version

All set-* and set commands accept --hash HASH to target a single key, --all to operate on all keys and --dry-run to preview changes.

For set-min, set-max, and set, you can pass --absolute to treat the amount as an absolute remaining value as if usage were 0. This effectively uses new_limit = amount (instead of usage + amount), which is useful when you want to set limits independent of current usage.

Multiple Configuration Files

The --suffix option allows you to maintain separate configuration files for different purposes (e.g., personal, work, testing environments). When using --suffix NAME, the configuration file becomes openrouter-control-NAME.json instead of the default openrouter-control.json.

# Use default config file
./openrouter-control usage

# Use personal config file (openrouter-control-personal.json)
./openrouter-control --suffix personal usage

# Use work config file (openrouter-control-work.json)  
./openrouter-control --suffix work create "Work Project" 100

# Show config file path for specific suffix
./openrouter-control --suffix personal config-path

Each suffixed configuration maintains its own provisioning key and operates independently. This is useful for:

• Separating personal and work OpenRouter accounts
• Managing different environments (dev, staging, prod)
• Testing configurations without affecting your main setup

CSV and JSON Export

The usage, audit, set-min, set-max, set, and add commands support CSV export via the --csv FILENAME option and JSON export via the --json FILENAME option. These files contain the same data shown in the tables. CSV output is formatted for spreadsheets while JSON output is convenient for other programs.

CSV Formats:

• usage and audit: Hash, Name, Usage, Limit, Remaining $, Remaining %
• set-min, set-max, set, add: Hash, Name, Usage, Old Limit, New Limit, Remaining $, Remaining %, Adjustment

Examples

# Basic commands (Unix/Linux/macOS)
./openrouter-control info
./openrouter-control audit 10 25%
./openrouter-control create "My Project" 50
./openrouter-control set-min 5 --hash abc12345
./openrouter-control delete abc12345
./openrouter-control debuginfo

# Using different configuration files
./openrouter-control --suffix personal usage
./openrouter-control --suffix work create "Work Key" 100
./openrouter-control --suffix test reset

# Basic commands (Windows)
python openrouter-control info
python openrouter-control audit 10 25%
python openrouter-control create "My Project" 50
python openrouter-control set-min 5 --hash abc12345
python openrouter-control delete abc12345
python openrouter-control debuginfo

# Using different configuration files
python openrouter-control --suffix personal usage
python openrouter-control --suffix work create "Work Key" 100
python openrouter-control --suffix test reset

# CSV export examples
./openrouter-control usage --csv usage.csv
./openrouter-control audit 10 --csv low_budget_keys.csv
./openrouter-control audit 25% --csv low_percentage_keys.csv
./openrouter-control set-min 5 --all --dry-run --csv proposed_min_adjustments.csv
./openrouter-control set-max 50 --hash abc12345 --csv max_adjustment.csv
./openrouter-control set 25 --all --dry-run --csv set_all_to_25.csv
./openrouter-control set 25 --all --absolute --dry-run  # set remaining to $25 ignoring current usage
./openrouter-control add 5 --hash abc12345 --csv add_adjustment.csv
# JSON export examples
./openrouter-control usage --json usage.json
./openrouter-control audit 10 --json low_budget_keys.json
./openrouter-control set-min 5 --all --dry-run --json proposed_min_adjustments.json
./openrouter-control add 5 --all --dry-run --json add_all_5.json

Configuration File

The configuration file is stored in the directory reported by platformdirs.user_config_dir("openrouter-control"). Use config-path to print the exact path on your system. File permissions are set to owner read/write only.

By default, the configuration file is named openrouter-control.json. When using the --suffix option, the file becomes openrouter-control-{suffix}.json, allowing you to maintain multiple independent configurations.

Security Notes

• Provisioning Key Required: This tool specifically validates that you're using a provisioning key (not a regular API key). Provisioning keys have the necessary permissions to manage other API keys and budgets.
• The provisioning key is stored locally in plain text. Keep your system secure.
• You may provide the key via the OPENROUTER_PROVISIONING_KEY environment variable to skip interactive entry and avoid local storage.
• Key input uses getpass so it is not echoed to the terminal.
• Full API key values are only shown once when creating a key.

Requirements

• Python 3.6+
• requests
• platformdirs

See DESIGN.md for a deeper look at how the tool works.

Contributing

Bug reports and other contributions are welcome. Please visit the official repository at https://github.com/mcgroarty/openrouter-control to report issues, suggest features, or submit pull requests.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for the full license text.

Copyright 2025 McGroarty