CLI Reference

All Plandex CLI commands and their options.

Usage

plandex [command] [flags]
pdx [command] [flags] # 'pdx' is an alias for 'plandex'

Help

Built-in help.

plandex help
pdx h # alias

--all/-a: List all commands.

For help on a specific command, use:

plandex [command] --help

REPL

The easiest way to use Plandex is through the REPL. Start it in your project directory with:

plandex

or for short:

pdx

Flags

The REPL has a few convenient flags you can use to start it with different modes, autonomy settings, and model packs. You can pass any of these to plandex or pdx when starting the REPL.

  Mode
    --chat, -c     Start in chat mode (for conversation without making changes)
    --tell, -t     Start in tell mode (for implementation)

  Autonomy
    --no-auto      None → step-by-step, no automation
    --basic        Basic → auto-continue plans, no other automation
    --plus         Plus → auto-update context, smart context, auto-commit changes
    --semi         Semi-Auto → auto-load context
    --full         Full-Auto → auto-apply, auto-exec, auto-debug

  Models
    --daily        Daily driver pack (default models, balanced capability, cost, and speed)
    --strong       Strong pack (more capable models, higher cost and slower)
    --cheap        Cheap pack (less capable models, lower cost and faster)
    --oss          Open source pack (open source models)

All commands listed below can be run in the REPL by prefixing them with a backslash (\), e.g. \new.

Plans

new

Start a new plan.

plandex new
plandex new -n new-plan # with name

--name/-n: Name of the new plan. The name is generated automatically after first prompt if no name is specified on creation.

--context-dir/-d: Base directory to load context from when auto-loading context is enabled. Defaults to . (current directory). Set a different directoy if you don't want all files to be included in the project map.

--no-auto: Start the plan with auto-mode 'None' (step-by-step, no automation).

--basic: Start the plan with auto-mode 'Basic' (auto-continue plans, no other automation).

--plus: Start the plan with auto-mode 'Plus' (auto-update context, smart context, auto-commit changes).

--semi: Start the plan with auto-mode 'Semi-Auto' (auto-load context).

--full: Start the plan with auto-mode 'Full-Auto' (auto-apply, auto-exec, auto-debug).

--daily: Start the plan with the daily driver model pack.

--strong: Start the plan with the strong model pack.

--cheap: Start the plan with the cheap model pack.

--oss: Start the plan with the open source model pack.

plans

List plans. Output includes index, when each plan was last updated, the current branch of each plan, the number of tokens in context, and the number of tokens in the conversation (prior to summarization).

Includes full details on plans in current directory. Also includes names of plans in parent directories and child directories.

plandex plans
plandex plans --archived # list archived plans only

pdx pl # alias

--archived/-a: List archived plans only.

current

Show current plan. Output includes when the plan was last updated and created, the current branch, the number of tokens in context, and the number of tokens in the conversation (prior to summarization).

plandex current
pdx cu # alias

cd

Set current plan by name or index.

plandex cd # select from a list of plans
plandex cd some-plan # by name
plandex cd 4 # by index in `plandex plans`

With no arguments, Plandex prompts you with a list of plans to select from.

With one argument, Plandex selects a plan by name or by index in the plandex plans list.

delete-plan

Delete a plan by name, index, range, pattern, or select from a list.

plandex delete-plan # select from a list of plans
plandex delete-plan some-plan # by name
plandex delete-plan 4 # by index in `plandex plans`
plandex delete-plan 2-4 # by range of indices
plandex delete-plan 'docs-*' # by pattern
plandex delete-plan --all # delete all plans
pdx dp # alias

--all/-a: Delete all plans.

rename

Rename the current plan.

plandex rename # prompt for new name
plandex rename new-name # set new name

unarchive

Unarchive a plan.

plandex unarchive # select from a list of archived plans
plandex unarchive some-plan # by name
plandex unarchive 4 # by index in `plandex plans --archived`
pdx unarc # alias

Context

load

Load files, directories, directory layouts, URLs, notes, images, or piped data into context.

plandex load component.ts # single file
plandex load component.ts action.ts reducer.ts # multiple files
plandex load lib -r # loads lib and all its subdirectories
plandex load tests/**/*.ts # loads all .ts files in tests and its subdirectories
plandex load . --tree # loads the layout of the current directory and its subdirectories (file names only)
plandex load https://redux.js.org/usage/writing-tests # loads the text-only content of the url
npm test | plandex load # loads the output of `npm test`
plandex load -n 'add logging statements to all the code you generate.' # load a note into context
plandex load ui-mockup.png # load an image into context

pdx l component.ts # alias

--recursive/-r: Load an entire directory and all its subdirectories.

--tree: Load directory tree layout with file names only.

--map: Load file map of the given directory (function/method/class signatures, variable names, types, etc.)

--note/-n: Load a note into context.

--force/-f: Load files even when ignored by .gitignore or .plandexignore.

--detail/-d: Image detail level when loading an image (high or low)—default is high. See https://platform.openai.com/docs/guides/vision/low-or-high-fidelity-image-understanding for more info.

ls

List everything in the current plan's context. Output includes index, name, type, token size, when the context added, and when the context was last updated.

plandex ls

plandex list-context # longer alias

rm

Remove context by index, range, name, or glob.

plandex rm some-file.ts # by name
plandex rm app/**/*.ts # by glob pattern
plandex rm 4 # by index in `plandex ls`
plandex rm 2-4 # by range of indices

plandex remove # longer alias
plandex unload # longer alias

show

Output context by name or index.

plandex show some-file.ts # by name
plandex show 4 # by index in `plandex ls`

update

Update any outdated context.

plandex update
pdx u # alias

clear

Remove all context.

plandex clear

Control

tell

Describe a task.

plandex tell -f prompt.txt # from file
plandex tell # open vim to write prompt
plandex tell "add a cancel button to the left of the submit button" # inline

pdx t # alias

--file/-f: File path containing prompt.

--stop/-s: Stop after a single model response (don't auto-continue). Defaults to opposite of config value auto-continue.

--no-build/-n: Don't build proposed changes into pending file updates. Defaults to opposite of config value auto-build.

--bg: Run task in the background. Only allowed if --auto-load-context and --apply/-a are not enabled. Not allowed with the default autonomy level in Plandex v2.

--auto-update-context: Automatically confirm context updates. Defaults to config value auto-update-context.

--auto-load-context: Automatically load context using project map. Defaults to config value auto-load-context.

--smart-context: Use smart context to only load the necessary file(s) for each step during implementation. Defaults to config value smart-context.

--no-exec: Don't execute commands after successful apply. Defaults to opposite of config value can-exec.

--auto-exec: Automatically execute commands after successful apply without confirmation. Defaults to config value auto-exec.

--debug: Automatically execute and debug failing commands (optionally specify number of tries—default is 5). Defaults to config values of auto-debug and auto-debug-tries.

--apply/-a: Automatically apply changes (and confirm context updates). Defaults to config value auto-apply.

--commit/-c: Commit changes to git when --apply/-a is passed. Defaults to config value auto-commit.

--skip-commit: Don't commit changes to git. Defaults to opposite of config value auto-commit.

continue

Continue the plan.

plandex continue

pdx c # alias