Skip to content

CLI reorganization: desired state of CLI help #74

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

Closed
mvidner wants to merge 2 commits into from
Closed

CLI reorganization: desired state of CLI help #74

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37d1ed2
Design the docs for the reorganized CLI (Do Not Merge)
mvidner May 2, 2025
afb0c2c
consistent stdio for agama config and agama download
mvidner May 2, 2025
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
79 changes: 31 additions & 48 deletions docs/user/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,16 +92,23 @@ It is possible that many configuration settings do not have a value. Those setti

The output of command can be used as input for the "agama config load".

**Usage:** `agama config show`
**Usage:** `agama config show [OPTIONS]`

###### **Options:**

* `-o`, `--output <FILE_PATH>` — Save the output here (goes to stdout if not given)



## `agama config load`

Read and load a profile from the standard input

**Usage:** `agama config load`
**Usage:** `agama config load URL_OR_PATH`

###### **Arguments:**

* `<URL_OR_PATH>` — JSON file, URL or path or `-` for standard input
Copy link
Contributor

@imobachgs imobachgs May 2, 2025

Choose a reason for hiding this comment

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

Why do you need to specify -? I think that not specifying an URL_OR_PATH should be enough.

Copy link
Contributor Author

@mvidner mvidner May 2, 2025

Choose a reason for hiding this comment

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

BTW I was unsure so I asked Google AI for help.
Gemini 2.0 Flash: started off by getting cat wrong (saying that cat needed an explicit argument)
Gemini Deep research 2.5 Pro: its report convinced me that requiring an explicit - is too strict



## `agama config edit`
Expand Down Expand Up @@ -142,73 +149,46 @@ When the preconditions for the installation are not met, it informs the user and



## `agama profile`

Manage auto-installation profiles (retrieving, applying, etc.)

**Usage:** `agama profile <COMMAND>`

###### **Subcommands:**

* `autoyast` — Download the autoyast profile and print resulting json
* `validate` — Validate a profile using JSON Schema
* `evaluate` — Evaluate a profile, injecting the hardware information from D-Bus
* `import` — Process autoinstallation profile and loads it into agama



## `agama profile autoyast`

Download the autoyast profile and print resulting json

**Usage:** `agama profile autoyast <URL>`

###### **Arguments:**

* `<URL>` — AutoYaST profile's URL. Any AutoYaST scheme, ERB and rules/classes are supported. all schemas that autoyast supports



## `agama profile validate`
## `agama config validate`

Validate a profile using JSON Schema

Schema is available at /usr/share/agama-cli/profile.schema.json

**Usage:** `agama profile validate <URL_OR_PATH>`
**Usage:** `agama config validate <URL_OR_PATH>`

###### **Arguments:**

* `<URL_OR_PATH>` — JSON file, URL or path or `-` for standard input


## `agama config generate`
Copy link
Contributor

@ancorgs ancorgs May 2, 2025

Choose a reason for hiding this comment

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

I don't fully understand how this command works.

Does it take any AutoYaST/Agama profile as input and generates the Agama config as output?

Does it export the current config into all those formats (I don't think so, but..)?

Copy link
Contributor

@imobachgs imobachgs May 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

It turns an AutoYaST or an Agama Jsonnet/JSON file and generates de configuration output. A few notes:

  • If given a URL, it downloads the file. Bear in mind that in AutoYaST, downloading the profile could imply more than one file (e.g., rules/classes).
  • For a JSON file, it just downloads the file and solves the relative URLs.
  • Reading from the stdin prevents downloading any file. It might be useful to convert an single-file AutoYaST profile or a Jsonnet one.

Copy link
Contributor

@ancorgs ancorgs May 2, 2025

Choose a reason for hiding this comment

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

I understood it after writing my comment. I guess that "AutoAgama" will pipe a "config generate" to a "config load".

Copy link
Contributor

@ancorgs ancorgs May 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

So that current internal conversion becomes somehow more explicit and exposed.

Copy link
Contributor

@imobachgs imobachgs May 2, 2025

Choose a reason for hiding this comment

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

Yes, that's the point, to make the conversion more explicit. However, we cannot do agama config generate URL | agama config load because we might need to validate the result in the middle. But that's a different topic.

Copy link
Contributor Author

@mvidner mvidner May 6, 2025

Choose a reason for hiding this comment

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

However, we cannot do agama config generate URL | agama config load because we might need to validate the result in the middle. But that's a different topic.

It is quite relevant. I am leaning toward making validation automatic:

  • automatic and mandatory on input (load, edit)
  • automatic but optional (--no-validate) for output (generate, show). Remember how AY would export profiles that would not validate? Not Agama.
  • explicit by validate (which in light of the above is just config blackhole but with an automatic validation part)

This way, agama config generate URL | agama config load performs validation twice, but I think it is a small price to pay for the resulting robustness for users and developers.


## `agama profile evaluate`

Evaluate a profile, injecting the hardware information from D-Bus

For an example of Jsonnet-based profile, see https://github.com/openSUSE/agama/blob/master/rust/agama-lib/share/examples/profile.jsonnet

**Usage:** `agama profile evaluate <URL_OR_PATH>`
Generate and print a native Agama JSON configuration from any kind and location.

###### **Arguments:**
**Usage:** `agama config generate [OPTIONS]`

* `<URL_OR_PATH>` — Jsonnet file, URL or path or `-` for standard input
###### **Options:**

* `-o`, `--output <FILE_PATH>` — Save the output here (goes to stdout if not given)

Kinds:
- JSON
- Jsonnet, injecting the hardware information from D-Bus (WTF D-Bus??)
Copy link
Contributor

@imobachgs imobachgs May 2, 2025

Choose a reason for hiding this comment

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

That's wrong. It does not use D-Bus at all.

- AutoYaST profile, including ERB and rules/classes
Locations:
- path
- URL (inlcuding AutoYaST specific schemes)
Copy link
Contributor

@ancorgs ancorgs May 2, 2025

Choose a reason for hiding this comment

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

Typo: inlcuding


## `agama profile import`

Process autoinstallation profile and loads it into agama
For an example of Jsonnet-based profile, see https://github.com/openSUSE/agama/blob/master/rust/agama-lib/share/examples/profile.jsonnet
Copy link
Contributor

@imobachgs imobachgs May 2, 2025

Choose a reason for hiding this comment

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

It should point to some profile at agama-project.github.io which should be a better place for user's documentation.


This is top level command that do all autoinstallation processing beside starting installation. Unless there is a need to inject additional commands between processing use this command instead of set of underlying commands.

**Usage:** `agama profile import <URL>`
**Usage:** `agama config generate <URL_OR_PATH>`

###### **Arguments:**

* `<URL>` — Profile's URL. Supports the same schemas as the "download" command plus AutoYaST specific ones. Supported files are json, jsonnet, sh for Agama profiles and ERB, XML, and rules/classes directories for AutoYaST support

* `<URL_OR_PATH>` — file, URL or path or `-` for standard input
Copy link
Contributor

@imobachgs imobachgs May 2, 2025

Choose a reason for hiding this comment

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

Reading from the standard input could be useful to translate from Jsonnet or XML.



## `agama questions`
Expand Down Expand Up @@ -368,12 +348,15 @@ Download file from given URL

The purpose of this command is to download files using AutoYaST supported schemas (e.g. device:// or relurl://). It can be used to download additional scripts, configuration files and so on. You can use it for downloading Agama autoinstallation profiles. However, unless you need additional processing, the "agama profile import" is recommended. If you want to convert an AutoYaST profile, use "agama profile autoyast".

**Usage:** `agama download <URL> <DESTINATION>`
**Usage:** `agama download [OPTIONS] <URL>`
Copy link
Contributor

@imobachgs imobachgs May 2, 2025

Choose a reason for hiding this comment

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

This command prints some information about which devices is trying. In the future, it could even display some progress information. For that reason, we might want to add a flag to disable/enable such a behavior (-q or -v, I am not sure what is better).

Copy link
Contributor Author

@mvidner mvidner May 2, 2025

Choose a reason for hiding this comment

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

curl is similar in displaying progress via stderr, maybe we want to model that behavior: https://www.man7.org/linux/man-pages/man1/curl.1.html#PROGRESS_METER


###### **Options:**

* `-o`, `--output <FILE_PATH>` — Save the output here (goes to stdout if not given)

###### **Arguments:**

* `<URL>` — URL pointing to file for download
* `<DESTINATION>` — File name



Expand Down