Skip to content

CLI reference updated for agama config generate and related changes #84

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
mvidner merged 2 commits into from
Jun 11, 2025
Merged

CLI reference updated for agama config generate and related changes #84

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fae9820
CLI reference updated for `agama config generate` and related changes
mvidner Jun 4, 2025
31efc3c
cli.md: update `agama config` bits
mvidner Jun 10, 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
151 changes: 75 additions & 76 deletions docs/user/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,11 @@ This document contains the help content for the `agama` command-line program.
* [`agama config`↴](#agama-config)
* [`agama config show`↴](#agama-config-show)
* [`agama config load`↴](#agama-config-load)
* [`agama config validate`↴](#agama-config-validate)
* [`agama config generate`↴](#agama-config-generate)
* [`agama config edit`↴](#agama-config-edit)
* [`agama probe`↴](#agama-probe)
* [`agama install`↴](#agama-install)
* [`agama profile`↴](#agama-profile)
* [`agama profile autoyast`↴](#agama-profile-autoyast)
* [`agama profile validate`↴](#agama-profile-validate)
* [`agama profile evaluate`↴](#agama-profile-evaluate)
* [`agama profile import`↴](#agama-profile-import)
* [`agama questions`↴](#agama-questions)
* [`agama questions mode`↴](#agama-questions-mode)
* [`agama questions answers`↴](#agama-questions-answers)
Expand All @@ -30,6 +27,8 @@ This document contains the help content for the `agama` command-line program.
* [`agama auth show`↴](#agama-auth-show)
* [`agama download`↴](#agama-download)
* [`agama finish`↴](#agama-finish)
* [`agama monitor`↴](#agama-monitor)
* [`agama events`↴](#agama-events)

## `agama`

Expand All @@ -46,12 +45,13 @@ Please, use the "help" command to learn more.
* `config` — Inspect or change the installation settings
* `probe` — Analyze the system
* `install` — Start the system installation
* `profile` — Manage auto-installation profiles (retrieving, applying, etc.)
* `questions` — Handle installer questions
* `logs` — Collect the installer logs
* `auth` — Authenticate with Agama's server
* `download` — Download file from given URL
* `download` — Download file from a given (AutoYaST) URL
* `finish` — Finish the installation
* `monitor` — Monitors the Agama service
* `events` — Display Agama events

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

Expand Down Expand Up @@ -79,7 +79,9 @@ If you want to change any configuration value, you can load a profile (complete
###### **Subcommands:**

* `show` — Generate an installation profile with the current settings
* `load` — Read and load a profile from the standard input
* `load` — Read and load a profile
* `validate` — Validate a profile using JSON Schema
* `generate` — Generate and print a native Agama JSON configuration from any kind and location.
* `edit` — Edit and update installation option using an external editor


Expand All @@ -92,122 +94,99 @@ 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`



## `agama config load`

Read and load a profile from the standard input

**Usage:** `agama config load`



## `agama config edit`

Edit and update installation option using an external editor.

The changes are not applied if the editor exits with an error code.

If an editor is not specified, it honors the EDITOR environment variable. It falls back to `/usr/bin/vi` as a last resort.

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

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

* `-e`, `--editor <EDITOR>` — Editor command (including additional arguments if needed)

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


## `agama probe`

Analyze the system.

In Agama's jargon, the term 'probing' refers to the process of 'analyzing' the system. This includes reading software repositories, analyzing storage devices, and more. The 'probe' command initiates this analysis process and returns immediately. TODO: do we really need a "probe" action?
## `agama config load`

**Usage:** `agama probe`
Read and load a profile

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

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

## `agama install`
* `<URL_OR_PATH>` — JSON file: URL or path or `-` for standard input

Start the system installation.

This command starts the installation process. Beware it is a destructive operation because it will set up the storage devices, install the packages, etc.

When the preconditions for the installation are not met, it informs the user and returns, making no changes to the system.
## `agama config validate`

**Usage:** `agama install`
Validate a profile using JSON Schema

Schema is available at /usr/share/agama-cli/profile.schema.json Note: validation is always done as part of all other "agama config" commands.

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

## `agama profile`
###### **Arguments:**

Manage auto-installation profiles (retrieving, applying, etc.)
* `<URL_OR_PATH>` — JSON file, URL or path or `-` for standard input

**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 config generate`

Generate and print a native Agama JSON configuration from any kind and location.

Kinds:
- JSON
- Jsonnet, injecting the hardware information
- AutoYaST profile, including ERB and rules/classes

## `agama profile autoyast`
Locations:
- path
- URL (including AutoYaST specific schemes)

Download the autoyast profile and print resulting json
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 autoyast <URL>`
**Usage:** `agama config generate [URL_OR_PATH]`

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

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

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


## `agama profile validate`

Validate a profile using JSON Schema

Schema is available at /usr/share/agama-cli/profile.schema.json
## `agama config edit`

**Usage:** `agama profile validate <URL_OR_PATH>`
Edit and update installation option using an external editor.

###### **Arguments:**
The changes are not applied if the editor exits with an error code.

* `<URL_OR_PATH>` — JSON file, URL or path or `-` for standard input
If an editor is not specified, it honors the EDITOR environment variable. It falls back to `/usr/bin/vi` as a last resort.

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

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

## `agama profile evaluate`
* `-e`, `--editor <EDITOR>` — Editor command (including additional arguments if needed)

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>`
## `agama probe`

###### **Arguments:**
Analyze the system.

* `<URL_OR_PATH>` — Jsonnet file, URL or path or `-` for standard input
In Agama's jargon, the term 'probing' refers to the process of 'analyzing' the system. This includes reading software repositories, analyzing storage devices, and more. The 'probe' command initiates this analysis process and returns immediately. TODO: do we really need a "probe" action?

**Usage:** `agama probe`


## `agama profile import`

Process autoinstallation profile and loads it into agama
## `agama install`

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.
Start the system installation.

**Usage:** `agama profile import <URL>`
This command starts the installation process. Beware it is a destructive operation because it will set up the storage devices, install the packages, etc.

###### **Arguments:**
When the preconditions for the installation are not met, it informs the user and returns, making no changes to the system.

* `<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
**Usage:** `agama install`



Expand Down Expand Up @@ -364,15 +343,15 @@ Print the used token to the standard output

## `agama download`

Download file from given URL
Download file from a given (AutoYaST) 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".
The purpose of this command is to download files using AutoYaST supported schemas (e.g. device://). It can be used to download additional scripts, configuration files and so on. You can use it for downloading Agama autoinstallation profiles. If you want to convert an AutoYaST profile, use "agama config generate".

**Usage:** `agama download <URL> <DESTINATION>`

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

* `<URL>` — URL pointing to file for download
* `<URL>` — URL reference pointing to file for download. If a relative URL is provided, it will be resolved against the current working directory
* `<DESTINATION>` — File name


Expand All @@ -399,5 +378,25 @@ Finish the installation



## `agama monitor`

Monitors the Agama service

**Usage:** `agama monitor`



## `agama events`

Display Agama events

**Usage:** `agama events [OPTIONS]`

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

* `-p`, `--pretty` — Display the events in a more human-readable way



---
NOTE: This documentation is generated. Run `cargo xtask markdown` to update it.