Submit an issue View all issues Source
MIR-746

Improve admin CLI per-method parameter help UX

In Progress public
phinze phinze Opened Mar 3, 2026 Updated May 26, 2026

Context

The miren admin CLI has good method introspection via --list, but the per-method help experience has several friction points. When you're trying to call a specific method and get the params wrong, the feedback is minimal compared to the rich info available through --list.

Discovery session that surfaced these issues:

# This shows rich, tree-structured output with types — great!
$ miren admin -a cloud --list
  labs.setOrgFlag
  │ Set or update an org-specific feature flag override (labs)
  ├ enabled boolean
  ├ name string
  └ org_xid string

# But calling a method with missing params falls through to raw JSON-RPC error
$ miren admin -a cloud labs.setOrgFlag
ERROR: admin call failed (code -32602): Invalid params

# Natural instinct is --help, but it's treated as an unknown param
$ miren admin -a cloud labs.setOrgFlag --help
ERROR: unknown parameter(s): help

Expected parameters:
  enabled
  name
  org_xid

# The actual flag is --func-help, but you'd never guess that
$ miren admin -a cloud labs.setOrgFlag --func-help
# (shows method details)

Problems

  1. --help doesn't work per-method — It's captured as an unknown flag and rejected. The actual flag is --func-help, which is undiscoverable unless you read miren admin --help carefully. Users (and AI agents) naturally reach for --help.
  2. Error param list is bare names only — When validation fails, "Expected parameters:" shows just names (enabled, name, org_xid) with no types or required/optional status. All that metadata is available from $methods — the --list output shows it — but the error path doesn't use it.
  3. Missing required params fall through to server — Calling a method with zero params when params are required gives a raw JSON-RPC error (Invalid params) instead of catching it locally and showing helpful output. The client-side validation in validateAdminCall() checks for missing required params, but this only works when the method schema marks params as required — many methods don't, so the call goes through with empty params and fails server-side.

Suggested Improvements

Intercept --help as method help (high value)

In parseUnknownFlags() or the main Admin() handler, detect when help appears as a flag and treat it as equivalent to --func-help. This matches the natural CLI UX expectation.

Enrich error output with types and descriptions

When validateAdminCall() produces error messages (unknown params, missing required params), render the method's parameter info using the same rich format as --list instead of bare names. The method metadata is already fetched during validation — just render it properly.

Show method help when called with no params

When a method is called with zero params and the method has defined params, show the method help (like --func-help) instead of sending an empty call to the server. This turns a confusing error into a teaching moment.

Relevant Code

  • CLI command: cli/commands/admin.go
    • Admin() main handler (~line 20)
    • parseUnknownFlags() (~line 266) — where --help gets captured as unknown
    • validateAdminCall() (~line 381) — error messages with bare param names
    • adminMethodHelp() (~line 529) — the --func-help handler with rich output
    • adminListMethods() (~line 462) — rich --list rendering
  • Admin RPC schema: api/admin/rpc.yml
  • Server-side method fetching: servers/admin/admin.go fetchMethods() (~line 318)