Refactor CLI subcommands to use --option syntax

Resolved 💬 4 comments Opened Jul 11, 2025 by archer-eric Closed Dec 30, 2025

Bug Description

Problem: The claude CLI treats the command line argument as either a prompt or a subcommand, depending on the content.

The current practice of using subcommands like claude update and claude doctor creates risks including:

  1. Users may accidentally type the wrong subcommand and invoke Claude Code with an unintended prompt
  2. Anthropic may release a new subcommand that users have already been using as a prompt to take some pre-defined action in some project, breaking the application

Example demonstrating the risk

The claude update subcommand is used to upgrade the Claude Code installation:

$ claude update
Current version: 1.0.48
Checking for updates...
Claude Code is up to date (1.0.48)

If the user doesn't remember that the magic word is "update" and accidentally types "upgrade" to perform the upgrade, then Claude Code interprets this as a prompt instead of a subcommand, and starts work that the user may not desire:

$ claude upgrade
╭───────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code!                         │
│                                                   │
│   /help for help, /status for your current setup  │
│                                                   │
│   cwd: /home/elided/src/tiktoken                   │
╰───────────────────────────────────────────────────╯

 Tips for getting started:

 1. Run /init to create a CLAUDE.md file with instructions for Claude
 2. Use Claude to help with file analysis, editing, bash commands and git
 3. Be as specific as you would with another engineer for the best results

> upgrade

● I'll help you upgrade the tiktoken project. Let me first understand the
  current state of the project and what needs to be upgraded.

● Update Todos
  ⎿  ☐ Check README and documentation for upgrade information
     ☐ Identify current dependencies and versions
     ☐ Check for available updates
     ☐ Review breaking changes and migration guides
     ☐ Perform the upgrade
[...]

Proposal:

Consider implementing a two-or three-phase release.

In phase 1,

  • claude --update performs the update and is the preferred trigger
  • claude update still performs the update, but warns the user to convert to --update

In phase 2, claude update fails with an error pointing to --update.

Optional phase 3: claude update treats "update" as a prompt.

Environment Info

  • Platform: linux
  • Terminal: gnome-terminal
  • Version: 1.0.48
  • Feedback ID: e10ff5a1-503f-4a01-8a10-85f844daeceb

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗