asyncapi / asyncapi/cli

[BUG] Clarify usage format for --param flag in help command

Open
#1,977 5 comments 0 reactions 0 assignees View on GitHub
bug stale
Dominant language
TypeScript
Stars
272
Forks
375
Avg merge
3h 22m
Merged PRs (30d)
8

Description

### Describe the bug.

The current help description for the `--param` flag (`asyncapi generate fromTemplate --help`) is vague and does not indicate the required format for passing parameters.

Current Help Output:

-p, --param ... Additional param to pass to templates

This seems ambiguous. Users guessing other common formats (like colon separators) will encounter errors. While the CLI provides a helpful error message *after* the failure (`Error: ...It must be in the format of --param name1=value1`), this creates a poor user experience where a user must **fail first** to discover the correct syntax.

**Proposed Solution**

I have verified in the source code (`src/internal/flags/generate/fromTemplate.flags.ts` or `sharedFlags.ts`) that the CLI splits parameters using the `=` character.

I propose updating the flag description to include the example used in the error message.

**Current Code:**
```typescript
param: Flags.string({
char: 'p',
description: 'Additional param to pass to templates',
multiple: true
})
```

Proposed Change:

```typeScript

param: Flags.string({
char: 'p',
description: 'Additional param to pass to templates (e.g., --param sidebarOrganization=byTags)',
multiple: true
}),
```

### Expected behavior

The `--help` documentation should be preventive and self-contained. It should explicitly show the expected `key=value` format so users succeed on their first try.

### Screenshots

**Screenshots**

Image

Image

### How to Reproduce

1. Run `asyncapi generate fromTemplate --help`.
2. Observe the description for `-p, --param`.
3. Try running with a guessed format: `asyncapi generate ... --param key:value`.
4. Observe the error: `Error: Invalid param... It must be in the format of --param name1=value1`.

### 🖥️ Device Information [optional]

- Operating System (OS): Windows
- Browser: N/A
- Browser Version: N/A

### 👀 Have you checked for similar open issues?

- [x] I checked and didn't find similar issue

### 🏢 Have you read the Contributing Guidelines?

- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)

### Are you willing to work on this issue ?

Yes I am willing to submit a PR!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.