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.

(Should we also print issues that were fixed?)

I don't think so. Cognitive overhead for almost no benefit (I even would say none). Just output issues, if any, present after each operation. This implicitly means that previous displayed issues not rendered again were fixed.

Installation Summaries: In interactive mode, agama install should print an installation summary and require user confirmation.

Just use the same output created for the previously mentioned status command, with confirmation to proceed as you stated, but not a different output. Be consistent here.

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.

Inline Prompts: If a question arises in interactive mode, it should be asked directly in the CLI to allow the user to answer immediately.

👍

More ideas:

• Add useful information to agama version (or agama --version). When working with a DUD, the package version is useless, and given that it is a binary, you are never sure about which exact version you are running.
• We need to invest some time into a better monitor.

Installation Summaries: In interactive mode, agama install should print an installation summary and require user confirmation.

Just use the same output created for the previously mentioned status command, with confirmation to proceed as you stated, but not a different output. Be consistent here.

@dgdavid so you think that agama status should print installation summary? It is kind of different command for me. I see it more as

• agama status - in which state agama is ( ready for install, some issues, some questions, busy )
• agama install or agama summary - prints what agama compute as proposal including storage actions, software overview, etc. Something like home page of agama before you click install

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.

Installation Summaries: In interactive mode, agama install should print an installation summary and require user confirmation.

Just use the same output created for the previously mentioned status command, with confirmation to proceed as you stated, but not a different output. Be consistent here.

@dgdavid so you think that agama status should print installation summary? It is kind of different command for me. I see it more as

• agama status - in which state agama is ( ready for install, some issues, some questions, busy )

Ok, no strong opinion here.

• agama install or agama summary - prints what agama compute as proposal including storage actions, software overview, etc. Something like home page of agama before you click install

That's what I meant, drawing inspiration from current web UI overview to create something similar for this command. Provide a concise yet comprehensive summary of what will be done. I would mirror it at the point that agama install should show it with the prompt confirmation before continuing with installation. agama summary would coexists just for taking a look without meaning user wanna start the installation already.

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.