Skip to content

Open source AI coding agent. Designed for large projects and real world tasks.

Update documentation for multiple providers support

Dane Schneider3a3bed340772
diff --git a/README.md b/README.md
index 33c6df1c..d668afa1 100644
--- a/README.md
+++ b/README.md
@@ -156,21 +156,15 @@ curl -sL https://plandex.ai/install.sh | bash
| Option | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plandex Cloud (Integrated Models)** | • No separate accounts or API keys.<br/>• Easy multi-device usage.<br/>• Centralized billing, budgeting, usage tracking, and cost reporting.<br/>• Quickest way to [get started.](https://app.plandex.ai/start?modelsMode=integrated) |
-| **Plandex Cloud (BYO API Key)** | • Use Plandex Cloud with your own [OpenRouter.ai](https://openrouter.ai) key (and **optionally** your own [OpenAI](https://platform.openai.com) key).<br/>• [Get started](https://app.plandex.ai/start?modelsMode=byo) |
-| **Self-hosted/Local Mode** | • Run Plandex locally with Docker or host on your own server.<br/>• Use your own [OpenRouter.ai](https://openrouter.ai) key (and **optionally** your own [OpenAI](https://platform.openai.com) key).<br/>• Follow the [local-mode quickstart](./hosting/self-hosting.md) to get started. |
+| **Plandex Cloud (BYO API Key)** | • Use Plandex Cloud with your own [OpenRouter.ai](https://openrouter.ai) key (or [other model provider](https://docs.plandex.ai/models/model-providers) accounts and API keys).<br/>• [Get started](https://app.plandex.ai/start?modelsMode=byo) |
+| **Self-hosted/Local Mode** | • Run Plandex locally with Docker or host on your own server.<br/>• Use your own [OpenRouter.ai](https://openrouter.ai) key (or [other model provider](https://docs.plandex.ai/models/model-providers) accounts and API keys).<br/>• Follow the [local-mode quickstart](./hosting/self-hosting.md) to get started. |
## Provider keys  🔑
-If you're going with a 'BYO API Key' option above (whether cloud or self-hosted), you'll need to set the `OPENROUTER_API_KEY` environment variable before continuing:
+<!-- If you're going with a 'BYO API Key' option above (whether cloud or self-hosted), you'll need to set API keys for the [model providers](https://docs.plandex.ai/models/model-providers) you're using: -->
```bash
-export OPENROUTER_API_KEY=...
-```
-
-You can also **optionally** set a `OPENAI_API_KEY` environment variable if you want OpenAI models to use the OpenAI API directly instead of OpenRouter (for slightly lower latency and costs):
-
-```bash
-export OPENAI_API_KEY=...
+export OPENROUTER_API_KEY=... # if using OpenRouter.ai
```
<br/>
diff --git a/docs/docs/cli-reference.md b/docs/docs/cli-reference.md
index ed1ad448..b93e0684 100644
--- a/docs/docs/cli-reference.md
+++ b/docs/docs/cli-reference.md
@@ -107,7 +107,7 @@ plandex new -n new-plan # with name
`--oss`: Start the plan with the open source model pack.
-`--gemini-exp`: Start the plan with the Gemini experimental model pack.
+`--gemini-preview`: Start the plan with the Gemini preview model pack.
### plans
@@ -667,6 +667,28 @@ Show org-wide default models and model settings for new plans.
plandex models default
```
+### models custom
+
+Manage custom models, providers, and model packs via JSON file.
+
+```bash
+plandex models custom
+plandex models custom --save # save changes from the default custom-models.json file to the server
+plandex models custom --file /path/to/models.json # import custom models/providers/model-packs from a non-default JSON file
+```
+
+`--save`: Save changes from the JSON file to the server.
+
+`--file/-f`: Path to non-default custom models JSON file.
+
+Without `--save`, this command will:
+
+- Create an example models file if none exists, or sync current server state to the file
+- Open the file in your configured editor
+- Prompt you to save changes when you return
+
+With `--save`, it will skip opening the editor and sync changes from the JSON file to the server.
+
### models available
Show available models.
@@ -678,94 +700,81 @@ plandex models available --custom # show available custom models only
`--custom`: Show available custom models only.
-### set-model
+### providers
-Update current plan models or model settings.
+Show all available model providers.
```bash
-plandex set-model # select from a list of models and settings
-plandex set-model planner openai/gpt-4 # set the model for a role
-plandex set-model gpt-4-turbo-latest # set the current plan's model pack by name (sets all model roles at once—see `model-packs` below)
-plandex set-model builder temperature 0.1 # set a model setting for a role
-plandex set-model max-tokens 4000 # set the planner model overall token limit to 4000
-plandex set-model max-convo-tokens 20000 # set how large the conversation can grow before Plandex starts using summaries
+plandex providers
+plandex providers --custom # show custom providers only (not supported on Plandex Cloud)
```
-With no arguments, Plandex prompts you to select from a list of models and settings.
-
-With arguments, can take one of the following forms:
-
-- `plandex set-model [role] [model]`: Set the model for a role.
-- `plandex set-model [model-pack]`: Set the current plan's model pack by name.
-- `plandex set-model [role] [setting] [value]`: Set a model setting for a role.
-- `plandex set-model [setting] [value]`: Set a model setting for the current plan.
+`--custom/-c`: Show custom providers only (not supported on Plandex Cloud).
-Models are specified as `provider/model-name`, e.g. `openai/gpt-4`, `openrouter/anthropic/claude-opus-3`, `together/mistralai/Mixtral-8x22B-Instruct-v0.1`, etc.
-
-See all the model roles [here](./models/roles.md).
+### set-model
-Model role settings:
+Update current plan models or model settings.
-- `temperature`: Higher temperature means more randomness, which can produce more creativity but also more errors.
-- `top-p`: Top-p sampling is a way to prevent the model from generating improbable text by only considering the most likely tokens.
+```bash
+plandex set-model # select from a list of model packs or edit via JSON
+plandex set-model daily # set model pack by name
+plandex set-model --json # edit plan's model settings via JSON file at default path
+plandex set-model --save # save changes from the plan's model settings JSON file to the server
+plandex set-model --json --file /path/to/settings.json # set plan's model settings from a JSON file at a non-default path
+```
-Plan settings:
+`--json`: Edit plan's model settings via JSON file at default path.
-- `max-tokens`: The overall token limit for the planner model.
-- `max-convo-tokens`: How large the conversation can grow before Plandex starts using summaries.
-- `reserved-output-tokens`: The number of tokens reserved for output from the model.
+`--save`: Save changes from the plan's model settings JSON file to the server.
-### set-model default
+`--file`: Set plan's model settings from a JSON file at a non-default path.
-Update org-wide default model settings for new plans.
+With no arguments, Plandex prompts you to either select a model pack or edit settings via JSON.
-```bash
-plandex set-model default # select from a list of models and settings
-plandex set-model default planner openai/gpt-4 # set the model for a role
-# etc. — same options as `set-model` above
-```
+When using JSON mode without `--save`, Plandex will:
-Works exactly the same as `set-model` above, but sets the default model settings for all new plans instead of only the current plan.
+- Write current settings to a JSON file
+- Open it in your configured editor
+- Apply the changes when you save and return
-### models add
+With `--save`, it will skip opening the editor and sync changes from the JSON file to the server.
-Add a custom model.
+Model pack shortcuts are still available:
```bash
-plandex models add
+plandex set-model daily
+plandex set-model reasoning
+plandex set-model strong
+plandex set-model cheap
+plandex set-model oss
+plandex set-model gemini-preview
```
-Plandex will prompt you for all required information to add a custom model.
-
-### models delete
+### set-model default
-Delete a custom model.
+Update org-wide default model settings for new plans.
```bash
-plandex models delete # select from a list of custom models
-plandex models delete some-model # by name
-plandex models delete 4 # by index in `plandex models available --custom`
+plandex set-model default # select from a list of model packs or edit via JSON
+plandex set-model default daily # set default model pack by name
+plandex set-model default --json # edit default settings via JSON file at default path
+plandex set-model default --save # save changes from the default model settings JSON file to the server
+plandex set-model default --json --file /path/to/settings.json # set default model settings from a JSON file at a non-default path
```
+Works exactly the same as `set-model` above, but sets the default model settings for all new plans instead of only the current plan.
+
### model-packs
Show all available model packs.
```bash
-plandex model-packs
+plandex model-packs # list built-in and custom model packs
+plandex model-packs --custom # list custom model packs only
```
`--custom`: Show available custom (user-created) model packs only.
-### model-packs create
-
-Create a new custom model pack.
-
-```bash
-plandex model-packs create
-```
-
-Plandex will prompt you for all required information to create a custom model pack.
### model-packs show
@@ -776,25 +785,6 @@ plandex model-packs show # select from a list of built-in and custom model packs
plandex model-packs show some-model-pack # by name
```
-### model-packs update
-
-Update a custom model pack's settings.
-
-```bash
-plandex model-packs update # select from a list of custom model packs
-plandex model-packs update some-model-pack # by name
-```
-
-### model-packs delete
-
-Delete a custom model pack.
-
-```bash
-plandex model-packs delete
-plandex model-packs delete some-model-pack # by name
-plandex model-packs delete 4 # by index in `plandex model-packs --custom`
-```
-
## Account Management
### sign-in
diff --git a/docs/docs/environment-variables.md b/docs/docs/environment-variables.md
index 0a4887b3..00dc1163 100644
--- a/docs/docs/environment-variables.md
+++ b/docs/docs/environment-variables.md
@@ -19,11 +19,39 @@ PLANDEX_API_HOST= # Defaults to 'http://localhost:8099' if PLANDEX_ENV is develo
### LLM Providers
```bash
-OPENAI_API_KEY= # Your OpenAI key (if self-hosting or using BYO API Key mode with Plandex Cloud)
-OPENROUTER_API_KEY= # Your OpenRouter.ai API key (if self-hosting or using BYO API Key mode with Plandex Cloud)
+# OpenRouter.ai
+OPENROUTER_API_KEY= # Your OpenRouter.ai API key
-OPENAI_API_BASE= # Your OpenAI server, such as http://localhost:1234/v1 Defaults to empty.
+# OpenAI
+OPENAI_API_KEY= # Your OpenAI key
OPENAI_ORG_ID= # Your OpenAI organization ID. Defaults to empty.
+
+# Anthropic
+ANTHROPIC_API_KEY= # Your Anthropic API key
+
+# Google AI Studio
+GEMINI_API_KEY= # Your Google AI Studio API key
+
+# Google Vertex AI
+GOOGLE_APPLICATION_CREDENTIALS= # Your Google Vertex AI credentials file path
+VERTEXAI_PROJECT= # Your Google Vertex AI project ID
+VERTEXAI_LOCATION= # Your Google Vertex AI location
+
+# Azure OpenAI
+AZURE_OPENAI_API_KEY= # Your Azure OpenAI API key
+AZURE_API_BASE= # Your Azure OpenAI API base URL
+AZURE_API_VERSION= # Your Azure OpenAI API version
+
+# DeepSeek
+DEEPSEEK_API_KEY= # Your DeepSeek API key
+
+# Perplexity
+PERPLEXITY_API_KEY= # Your Perplexity API key
+
+# Amazon Bedrock
+AWS_ACCESS_KEY_ID= # Your AWS access key ID
+AWS_SECRET_ACCESS_KEY= # Your AWS secret access key
+AWS_REGION= # Your AWS region
```
### Upgrades
diff --git a/docs/docs/install.md b/docs/docs/install.md
index 76a34c8d..f7ed5482 100644
--- a/docs/docs/install.md
+++ b/docs/docs/install.md
@@ -28,8 +28,4 @@ mv plandex /usr/local/bin # adapt as needed for your system
Windows is supported via [WSL](https://learn.microsoft.com/en-us/windows/wsl/about).
-Plandex only works correctly in the WSL shell. It doesn't work in the Windows CMD prompt or PowerShell.
-
-## Upgrading from v1 to v2
-
-When you install the Plandex v2 CLI with the quick install script, it will rename your existing `plandex` command to `plandex1` (and the `pdx` alias to `pdx1`). Plandex v2 is designed to run *separately* from v1 rather than upgrading in place. [More details here.](./upgrading-v1-to-v2.md)
\ No newline at end of file
+Plandex only works correctly in the WSL shell. It doesn't work in the Windows CMD prompt or PowerShell.
\ No newline at end of file
diff --git a/docs/docs/quick-start.md b/docs/docs/quick-start.md
index 6499e9f1..bbc81257 100644
--- a/docs/docs/quick-start.md
+++ b/docs/docs/quick-start.md
@@ -20,19 +20,15 @@ Note that Windows is supported via [WSL](https://learn.microsoft.com/en-us/windo
| Option | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plandex Cloud (Integrated Models)** | • No separate accounts or API keys.<br/>• Easy multi-device usage.<br/>• Centralized billing, budgeting, usage tracking, and cost reporting.<br/>• Quickest way to [get started.](https://app.plandex.ai/start?modelsMode=integrated) |
-| **Plandex Cloud (BYO API Key)** | • Use Plandex Cloud with your own [OpenRouter.ai](https://openrouter.ai) key (and **optionally** your own [OpenAI](https://platform.openai.com) key).<br/> |
-| **Self-hosted/Local Mode** | • Run Plandex locally with Docker or host on your own server.<br/>• Use your own [OpenRouter.ai](https://openrouter.ai) (and **optionally** your own [OpenAI](https://platform.openai.com) key).<br/>• Follow the [local-mode quickstart](./hosting/self-hosting/local-mode-quickstart.md) to get started. |
+| **Plandex Cloud (BYO API Key)** | • Use Plandex Cloud with your own [OpenRouter.ai](https://openrouter.ai) key (or [other model provider](./models/model-providers.md) accounts and API keys).<br/>• [Get started](https://app.plandex.ai/start?modelsMode=byo) |
+| **Self-hosted/Local Mode** | • Run Plandex locally with Docker or host on your own server.<br/>• Use your own [OpenRouter.ai](https://openrouter.ai) key (or [other model provider](./models/model-providers.md) accounts and API keys).<br/>• Follow the [local-mode quickstart](./hosting/self-hosting/local-mode-quickstart.md) to get started. |
-If you're going with a 'BYO API Key' option above (whether cloud or self-hosted), and you don't have an OpenRouter account, first [sign up here.](https://openrouter.ai/signup) Then [generate an API key here.](https://openrouter.ai/keys) Set the `OPENROUTER_API_KEY` environment variable:
+If you're going with a 'BYO API Key' option above (whether cloud or self-hosted), decide on the model provider(s) you want to use. The quickest option is to use OpenRouter.ai, but you can also use [many other providers](./models/model-providers.md).
-```bash
-export OPENROUTER_API_KEY=...
-```
-
-You can also **optionally** set a `OPENAI_API_KEY` environment variable if you want OpenAI models to use the OpenAI API directly instead of OpenRouter (for slightly lower latency and costs). This requires an [OpenAI account.](https://platform.openai.com/signup).
+If you're using OpenRouter.ai, first [sign up here.](https://openrouter.ai/signup) Then [generate an API key here.](https://openrouter.ai/keys) Set the `OPENROUTER_API_KEY` environment variable:
```bash
-export OPENAI_API_KEY=...
+export OPENROUTER_API_KEY=...
```
## Get Started