CLI

cli.md

Overview

Use Cases and Requirements

The Agama CLI serves two primary use cases, each with distinct functional requirements.

Scripting

Using the CLI within user scripts to create powerful automated workflows where an Agama profile is insufficient or requires specific integration into the user's environment.

Requirements:

• Non-interactive: Must run without requiring manual input.
• Clear error reporting: Transparent error messages and meaningful exit codes.
• Processable I/O: Easily machine-readable input and output (e.g., JSON).
• High observability: Scripts must be able to track state and progress to control the workflow effectively.
• Backward compatibility: Ensuring updates do not break existing automation.

Web Alternative

Using the CLI as an alternative to the web interface when environment or security restrictions prevent using a browser.

Requirements:

• Strong UX: Intuitive and easy to navigate for human operators.
• Decision support: Provide enough information for the user to make informed deployment decisions.
• Safety mechanisms: Confirmations for all destructive operations.
• Terminal flexibility: Support for colors and special characters while respecting restricted terminals on legacy platforms.
• Powerful commands: High-level commands that prevent users from needing a fragmented chain of commands (e.g., separate commands for config, status, and questions).

---

Pain Points

• Invisible Blockers: No way to see a comprehensive list of issues preventing an installation.
• Rigid Question Handling: Questions can only be listed via dedicated commands and answered via JSON (they are not integrated into the standard command flow).
• Vague Status: No easy way to see the current state of the installer (e.g., if it is waiting for an answer, processing, or finished successfully).
• Lack of Proposals: No way to get a pre-installation summary, such as which disks will be modified.
• Confusing Messaging: The "config validated" note is ambiguous.
• Inconsistent Output: Only a portion of the commands offer easily processable output.
• Fragmented Experience: Overall command structure feels inconsistent.
• Missing Information: Inability to list available products, patterns, or packages.

---

Ideas

The following improvements aim to address these pain points and align with the core requirements:

• Auto-mode for Questions: Use by default an "auto mode" for questions when running in non-interactive mode.
• Question Exit Codes: Alternatively, use a dedicated exit code when a question arises in non-interactive mode to signal the script.
• Agama Status Command: Implement a status command to print the installation stage, a list of issues, and pending questions.
• Clearer Validation: Reword validation messages to be more specific, such as "Syntax is correct."
• Dynamic Issue Reporting: When loading or editing a configuration, print new issues that appear. (Should we also print issues that were fixed?)
• Installation Summaries: In interactive mode, agama install should print an installation summary and require user confirmation.
• Proactive Error Checks: agama install should explicitly print any blocking issues before starting and exit with proper exit code.
• Inline Prompts: If a question arises in interactive mode, it should be asked directly in the CLI to allow the user to answer immediately.
• Useful Version: Add agama version command that returns useful information about agama version including DUD/self-update usage.
• Monitor Improvements: agama monitor deserve a bit lowe to show more visually appealing progress.

Proactive Error Checks: agama install should explicitly print any blocking issues before starting and exit with proper exit code.

This could follow the pattern already used in the web UI by showing the summary/status mentioned above and marking areas with issues with "Invalid settings" but without dumping every detail at once. Instead of showing all issues in a long output, which can be overwhelming on small terminals, we could provide targeted commands for exploring specific areas in more detail, for example agama storage issues, agama network issues or agama issues storage, it depends of the pattern chosen.
This keeps the default CLI output concise and user-friendly, while still giving users the ability to drill down when needed. For those who want a full overview, a flag such as agama status --verbose could be offered, pleasing all kind of workflows. Just an idea.

I kind of expect we usually do not have that much issues. So I would probably do not use dedicated commands and instead use something like Issues: Problem A description.\nThere are 7 more issues and allow to pass that --full to get full list.

Most probably I mixed some points before.

Thinking it twice, I would combine your proposal with mine:

• When users run agama install and there are issues, it should behave like the web UI: show a summary highlighting problematic areas without the option/question to continue but a suggestion for running agama issues to see the full list of issues instead. We could even offer in such a prompt if they wanna see the full list of issues (saving them to type agama issues)
• For agama issues, I would avoid limiting the output. Even if we usually expect only a few issues, showing all at once is more straightforward and scalable. It avoids forcing users to rerun the command with a flag and lets them see all problems upfront instead just the one we (randomly?) pick.