Skip to content

fix(command-parser): user-friendly errors for unknown commands and consistent list command output#3002

Merged
tusharmath merged 8 commits intomainfrom
app-command-parser
Apr 14, 2026
Merged

fix(command-parser): user-friendly errors for unknown commands and consistent list command output#3002
tusharmath merged 8 commits intomainfrom
app-command-parser

Conversation

@tusharmath
Copy link
Copy Markdown
Collaborator

@tusharmath tusharmath commented Apr 14, 2026

Summary

Improve the command-line and REPL experience by showing user-friendly error messages for unknown commands, fixing list command output, and adding a help action to the shell plugin.

Context

Previously, when a user typed an unknown command like :celar, the error message surfaced raw Clap internals (e.g. references to forge_cmd) with no guidance on how to recover. The list command output was also inconsistent: in non-porcelain mode it built a full Info table including agents and custom commands, while :help in the REPL used a different code path — so the two outputs diverged. The shell plugin also had no way to show available commands outside the REPL.

Changes

  • User-friendly unknown-command errors: When a user types an unrecognised command (e.g. :celar or /celar), the error now reads "Unknown command ':celar'. Run ':help' to list available commands." instead of a raw Clap error.
  • Cleaned-up Clap error output: The internal binary name forge_cmd is replaced with forge in all other Clap error messages.
  • Consistent list command output: Non-porcelain mode now delegates to ForgeCommandManager (the same path as :help), so forge list command and :help always render identically.
  • Shell plugin help action: Added _forge_action_help and wired it to the help keyword in the dispatcher so users can run help in the shell-plugin context and get the same output as :help.
  • Posthog dependency bump: Updated the posthog-rs git revision.

Key Implementation Details

  • The command prefix (/ or :) is captured before stripping it from the token, so the error message reflects exactly what the user typed.
  • Porcelain mode still builds the full Info table (built-ins + agent aliases + agent infos + custom commands) for shell-completion consumers; non-porcelain mode uses ForgeCommandManager::default() directly.
  • Two new unit tests cover the helpful error for both : and / prefixes.

Testing

# Verify unknown-command error messages
cargo insta test --accept -p forge_main

# Try it interactively
cargo run -- chat
# Then type:  :celar
# Expected:   Unknown command ':celar'. Run ':help' to list available commands.

# Verify list command (non-porcelain)
cargo run -- list command

# Verify list command (porcelain)
cargo run -- list command --porcelain

@tusharmath tusharmath changed the title app command parser fix(command-parser): user-friendly errors for unknown commands and consistent list command output Apr 14, 2026
@github-actions github-actions bot added the type: fix Iterations on existing features or infrastructure. label Apr 14, 2026
@tusharmath tusharmath merged commit 896d237 into main Apr 14, 2026
8 checks passed
@tusharmath tusharmath deleted the app-command-parser branch April 14, 2026 11:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type: fix Iterations on existing features or infrastructure.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant