Why do we need this improvement?

Right now, the .asyncapi-cli file is only used to store contexts (mapping context names to AsyncAPI spec file paths). This helps when working with multiple specs in the same project, but users still have to repeat the same CLI flags again and again for common workflows like generating docs or validating specs.
In real projects, developers usually run the same commands with the same options multiple times (for example, always generating HTML docs into the same folder, using the same template, or always validating with certain flags).
Because of this, the current workflow becomes repetitive and error-prone, especially for larger projects or in CI/CD pipelines. Adding support for per-command default options inside the existing .asyncapi-cli file would make the CLI more convenient, reduce repeated typing, and improve the overall developer experience without introducing a new config system.

How will this change help?

This change would allow users to define default options once and reuse them automatically across all CLI commands.

Some practical benefits:

• Developers won’t need to repeat flags like --template, --output, --force-write, etc.
• It will make CI/CD pipelines cleaner and easier to maintain, since commands will be shorter and more readable.
• Teams working on large projects with multiple AsyncAPI files will be able to standardize their CLI usage using a shared configuration.
• It builds on top of the existing .asyncapi-cli mechanism instead of introducing a separate config, making it easier for current users to adopt.
• Overall, this improves productivity and reduces cognitive load for anyone using AsyncAPI CLI regularly.

How could it be implemented/designed?

Extend the .asyncapi-cli file format
{
"contexts": {
"monitor": "services/monitor/asyncapi.yaml",
"notifier": "services/notifier/asyncapi.yaml"
},
"defaults": {
"generate:fromTemplate": {
"template": "@asyncapi/html-template",
"output": "./docs",
"forceWrite": true
},
"validate": {
"strict": true
}
}
}

Create a command identifier strategy
Use keys like:

• validate
• convert
• generate:fromTemplate

so each command/subcommand can have its own defaults.

Merge logic inside command handlers:
When a command runs:

• Load .asyncapi-cli if present.
• Check if defaults for that command exist.
• Merge them with the user-provided CLI flags.
• CLI flags should always override defaults.

Backward compatibility:
If the defaults section doesn’t exist:

• CLI should behave exactly as it does today.
• No changes to existing projects.

🚧 Breaking changes

No

👀 Have you checked for similar open issues?

• I checked and didn't find a similar issue

🏢 Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines

Are you willing to work on this issue?

Yes I am willing to submit a PR!