Skip to content

fix(schema): Add detailed reference for the root cli object #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ioncakephper merged 1 commit into from
Dec 8, 2025
Merged

fix(schema): Add detailed reference for the root cli object #15

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,25 @@ While the examples show a simple command, the schema is designed to handle enter

## Schema Reference

All CLI definitions must be nested under a top-level `cli` object. This root object contains all the commands, arguments, and options that define your command-line interface.
All CLI definitions must be nested under a top-level `cli` object. This root object is mandatory and serves as the container for all commands, arguments, and options that define your command-line interface. While other properties can exist alongside the `cli` object, they will not be validated by the schema.

### The `cli` Object

The `cli` object is the root of your CLI definition. It contains the following properties:

| Property | Type | Description |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | `string` | The name of your CLI application. **(Required)** |
| `version` | `string` | The version of your CLI. It is recommended to follow semantic versioning (e.g., `1.0.0`). |
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The documentation adds a version property to the cli object's reference table. However, this property is not defined in schema/cli.schema.json. This inconsistency can be misleading for users trying to create a valid CLI definition based on the schema. To ensure the documentation accurately reflects the schema, this property should be removed from the table. If supporting a version property is desired, the JSON schema should be updated first.

| `description` | `string` | A brief description of your CLI's purpose. |
| `sortCommands` | `boolean` | If `true`, help output will display commands in alphabetical order. |
| `sortOptions` | `boolean` | If `true`, help output will display options in alphabetical order. |
| `showGlobalOptions` | `boolean` | If `true`, global options will be displayed in the help output for subcommands. |
| `defaultConfigFile` | `string` | The path to a default configuration file that the CLI should load. |
| `fallbackConfig` | `object` | An object containing fallback configuration values to be used if the default configuration file is not found or does not contain a required value. |
| `arguments` | `array` | An array of `argument` objects for the root command. |
| `options` | `array` | An array of `option` objects for the root command. |
| `commands` | `array` | An array of nested `command` objects (subcommands). |

The `cli-schema` defines the structure for your CLI definition file. Here are the main building blocks:

Expand Down