Portkey CLI

Wire Claude Code or OpenAI Codex to Portkey (routing, logs, guardrails). Optionally add MCP servers and sync team skills from your workspace.

Install

Node.js 18+ required.

npx portkey

Or install globally:

npm install -g portkey
portkey

That opens the interactive menu (Setup Claude Code or Setup Codex). Have your Portkey API key ready (or set PORTKEY_API_KEY first).

Use the same prefix for every subcommand:

npx portkey setup
npx portkey status
npx portkey skills sync
npx portkey mcp add

---

Claude Code

1. Run npx portkey → choose Setup Claude Code.
2. Paste your Portkey API key when asked.
3. Pick a provider or Portkey config for routing.
4. Optionally add MCP servers and sync skills (prompt partials → SKILL.md).

Config goes mainly into your shell profile and/or .claude/ (the wizard explains each choice). Open a new terminal (or source your profile) after setup, then run claude as usual.

Later, from your project folder:

npx portkey skills sync --yes --agent claude
npx portkey mcp add

---

Codex

1. Run npx portkey → choose Setup Codex.
2. Paste your Portkey API key when asked.
3. Pick routing (provider or config). The CLI updates .codex/config.toml with base_url, PORTKEY_API_KEY, and wire_api (chat = Chat Completions, responses = Responses API — same as Portkey's Codex guide).
4. Optionally add MCP (same Portkey registry) and sync skills into .agents/skills/ (Codex's skill discovery location).

If you have several Model Catalog providers, the wizard can append extra [model_providers.portkey-<slug>] tables (each with its own wire_api). Switch the active route by editing model_provider and model (@<slug>/<model-id>) at the top of the file.

Non-interactive: pass --codex-wire-api chat or --codex-wire-api responses.

Then run codex from that project (or point Codex at the same directory).

Refresh skills only:

cd /path/to/your/project
npx portkey skills sync --yes --agent codex

---

Useful commands

Example	What it does
npx portkey	Interactive menu
npx portkey setup	Full wizard (Claude Code, Codex, or Cursor skills-only)
npx portkey status	Claude + Codex: routing hints and MCP counts
npx portkey skills sync	Pull Prompt Partials from Portkey → local SKILL.md trees
npx portkey skills list	List partials in the workspace
npx portkey mcp add	Pick Claude Code or Codex, then servers from Portkey

Skills: list comes from the Portkey API for your workspace. You choose where files are written (.claude/skills, .agents/skills for Codex, .cursor/skills, project vs --global).

MCP: same registry on Portkey; Claude uses ~/.claude.json / .mcp.json, Codex [mcp_servers.*] in .codex/config.toml.

Non-interactive setup: add --yes and flags such as --portkey-key, --provider, --skip-mcp, --skip-skills.

npx portkey --help

---

Contributing

git clone https://github.com/portkey-ai/agent-cli.git
cd agent-cli
npm install
npm test

---

Links

• Portkey dashboard · Docs