jackwener / jackwener/OpenCLI

[Feature]: support short option aliases in Arg schema

Open
#1,970 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
29.3k
Forks
2.9k
Avg merge
15h 36m
Merged PRs (30d)
70

Description

### Feature Description

OpenCLI command args currently expose long option names through `Arg.name`, and adapter/plugin options are registered as `--`. There does not appear to be a first-class way for an adapter to declare conventional short options such as `-l` for `--limit` or `-o` for `--output`.

This makes plugin authors either avoid short options entirely or add synthetic extra args and manually remap them inside the command implementation. That workaround is harder to document, shows up as separate options in help output, and does not behave like normal Commander short aliases.

### Use Case

As a plugin author, I want to define a canonical kebab-case long option and an optional single-letter alias in the command schema, so commands can provide normal CLI ergonomics without duplicating argument definitions.

Example desired declaration:

```ts
args: [
{ name: "limit", short: "l", type: "int", default: 20, help: "Maximum number of items" },
{ name: "output", short: "o", type: "str", help: "Output file path" },
]
```

Expected CLI behavior:

```bash
opencli some-site list --limit 10 --output result.json
opencli some-site list -l 10 -o result.json
```

Both forms should populate the same canonical kwargs keys:

```ts
kwargs.limit
kwargs.output
```

### Proposed Solution

Extend the `Arg` schema with an optional short alias field, for example:

```ts
interface Arg {
name: string;
short?: string;
type?: string;
default?: unknown;
required?: boolean;
positional?: boolean;
help?: string;
choices?: string[];
}
```

Then update `commanderAdapter.ts` so non-positional args with `short` are registered in Commander as `-${short}, --${name}` while still collecting values into the canonical `kwargs[name]` key.

Suggested validation:

- `short` must be a single ASCII letter or digit.
- `short` cannot collide with OpenCLI common options such as `-f` and `-v`.
- Duplicate short aliases within the same command should throw a clear adapter/schema error.
- Generated help and structured command metadata should include the alias.

### Alternatives Considered

Adapters can currently define separate synthetic args like `v` plus `version` and remap manually, but that is not equivalent to a true short option alias. It leaks implementation details into help output and forces each adapter to solve the same mapping/validation problem independently.

Contributor guide

Open the contributing guide

Research direction

Start with the Arg schema definition and commanderAdapter.ts, then trace how command help and structured metadata are generated. Check the existing adapter registration and option validation paths before defining the alias behavior. Done means short aliases work alongside canonical long-option keys, invalid or conflicting aliases produce clear errors, and help and metadata expose the alias.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.