From ba274d9a86c3528396120bd2c096b168f9b31041 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Imobach=20Gonz=C3=A1lez=20Sosa?= Date: Mon, 27 May 2024 22:55:16 +0100 Subject: [PATCH 1/3] Drop the "agama info" command because it is not implemented --- rust/agama-cli/src/commands.rs | 6 ------ rust/agama-cli/src/main.rs | 1 - 2 files changed, 7 deletions(-) diff --git a/rust/agama-cli/src/commands.rs b/rust/agama-cli/src/commands.rs index 46615a4abe..acce9033ca 100644 --- a/rust/agama-cli/src/commands.rs +++ b/rust/agama-cli/src/commands.rs @@ -11,12 +11,6 @@ pub enum Commands { #[command(subcommand)] Config(ConfigCommands), - /// Display information about installation settings (e.g., possible values) - Info { - /// Configuration keys (e.g., software.products) - keys: Vec, - }, - /// Start probing Probe, // Start Installation Install, diff --git a/rust/agama-cli/src/main.rs b/rust/agama-cli/src/main.rs index 33117ae481..c715aff589 100644 --- a/rust/agama-cli/src/main.rs +++ b/rust/agama-cli/src/main.rs @@ -138,7 +138,6 @@ async fn run_command(cli: Cli) -> anyhow::Result<()> { Commands::Questions(subcommand) => run_questions_cmd(subcommand).await, Commands::Logs(subcommand) => run_logs_cmd(subcommand).await, Commands::Auth(subcommand) => run_auth_cmd(subcommand).await, - _ => unimplemented!(), } } From 76e67e5e46ea11ec58bca37af5a4afa2307523f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Imobach=20Gonz=C3=A1lez=20Sosa?= Date: Mon, 27 May 2024 22:55:48 +0100 Subject: [PATCH 2/3] feat(rust): improve the CLI documentation --- rust/agama-cli/src/auth.rs | 11 +++--- rust/agama-cli/src/commands.rs | 61 +++++++++++++++++++++++++++------ rust/agama-cli/src/config.rs | 27 +++++++++++---- rust/agama-cli/src/logs.rs | 8 ++--- rust/agama-cli/src/main.rs | 8 ++++- rust/agama-cli/src/questions.rs | 18 +++++----- 6 files changed, 96 insertions(+), 37 deletions(-) diff --git a/rust/agama-cli/src/auth.rs b/rust/agama-cli/src/auth.rs index 4ca6224c6e..b922b8a68c 100644 --- a/rust/agama-cli/src/auth.rs +++ b/rust/agama-cli/src/auth.rs @@ -17,14 +17,15 @@ const DEFAULT_FILE_MODE: u32 = 0o600; #[derive(Subcommand, Debug)] pub enum AuthCommands { - /// Authenticate with Agama's server and store the credentials + /// Authenticate with Agama's server and store the token. /// - /// It reads the password from the standard input. If it is not available, - /// it asks the user. + /// This command tries to get the password from the standard input. If it is not there, it asks + /// the user interactively. Upon successful login, it stores the token in .agama/agama-jwt. The + /// token will be automatically sent to authenticate the following requests. Login, - /// Deauthenticate by removing the credentials + /// Deauthenticate by removing the token. Logout, - /// Prints currently stored credentials to the standard output + /// Print the used token to the standard output. Show, } diff --git a/rust/agama-cli/src/commands.rs b/rust/agama-cli/src/commands.rs index acce9033ca..a248a0de49 100644 --- a/rust/agama-cli/src/commands.rs +++ b/rust/agama-cli/src/commands.rs @@ -7,30 +7,69 @@ use clap::Subcommand; #[derive(Subcommand, Debug)] pub enum Commands { - /// Change or show installation settings + /// Change or show the installation settings. + /// + /// You can set any Agama configuration value from the command-line. You can change individual + /// values the "add" or "set" commands. Or modify many of them at a time by loading a so-called + /// profile through the "load" command. + /// + /// Use "show" to display the current configuration in JSON format. #[command(subcommand)] Config(ConfigCommands), + /// 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? Probe, - // Start Installation + + /// 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. Install, - /// Autoinstallation profile handling + + /// Manage auto-installation profiles (retrieving, applying, etc.). #[command(subcommand)] Profile(ProfileCommands), - /// Configuration for questions that come from installer + + /// Handle installer questions. /// - /// Questions are raised when an unexpected (by the user) situation happens in the installer: - /// like if an encrypted partition is detected and cannot be inspected, - /// if a repository is signed by an unknown GPG key, or if the installer is not sure - /// if multipath should be activated. + /// Agama might require user intervention at any time. The reasons include providing some + /// missing information (e.g., the password to decrypt a file system) or deciding what to do in + /// case of an error (e.g., cannot connect to the repository). /// - /// For more details see official agama documentation for Questions. + /// This command allows answering such questions directly from the command-line. #[command(subcommand)] Questions(QuestionsCommands), - /// Collects logs + + /// Collect the installer logs. + /// + /// The installer logs are stored in a compressed archive for further inspection. The file + /// includes system and Agama-specific logs and configuration files. They are crucial to + /// troubleshoot and debug problems. #[command(subcommand)] Logs(LogsCommands), - /// Request an action on the web server like Login / Logout + + /// Authenticate with Agama's server. + /// + /// Unless you are executing this program as root, you need to authenticate with Agama's server + /// for most operations. You can log in by specifying the root password through the "auth login" + /// command. Upon successful authentication, the server returns a JSON Web Token (JWT) which is + /// stored to authenticate the following requests. + /// + /// If you run this program as root, you can skip the authentication step because it + /// automatically uses the master token at /run/agama/token. Only the root user must have access + /// to such a file. + /// + /// You can logout at any time by using the "auth logout" command, although this command does + /// not affect the root user. #[command(subcommand)] Auth(AuthCommands), } diff --git a/rust/agama-cli/src/config.rs b/rust/agama-cli/src/config.rs index 627dd82c4d..7b55dfa3a3 100644 --- a/rust/agama-cli/src/config.rs +++ b/rust/agama-cli/src/config.rs @@ -15,16 +15,29 @@ use std::{collections::HashMap, error::Error, io, str::FromStr}; #[derive(Subcommand, Debug)] pub enum ConfigCommands { - /// Add an element to a collection + /// Add an element to a collection. + /// + /// In case of collections, this command allows adding a new element. For instance, let's add a + /// new item to the list of software patterns: + /// + /// $ agama config add software.patterns value=gnome Add { key: String, values: Vec }, + /// Set one or many installation settings - Set { - /// key-value pairs (e.g., user.name="Jane Doe") - values: Vec, - }, - /// Shows the value of one or many configuration settings + /// + /// For scalar values, this command allows setting a new value. For instance, let's change the + /// product to install: + /// + /// $ agama config set product.id=Tumbleweed + Set { values: Vec }, + + /// Shows the value of the configuration settings. + /// + /// It is possible that many configuration settings do not have a value. Those settings + /// are not included in the output. Show, - /// Loads the configuration from a JSON file + + /// Loads the configuration from a JSON file. Load { path: String }, } diff --git a/rust/agama-cli/src/logs.rs b/rust/agama-cli/src/logs.rs index 7038eaa121..8642d1ae63 100644 --- a/rust/agama-cli/src/logs.rs +++ b/rust/agama-cli/src/logs.rs @@ -14,17 +14,17 @@ use tempfile::TempDir; // definition of "agama logs" subcommands, see clap crate for details #[derive(Subcommand, Debug)] pub enum LogsCommands { - /// Collects and stores logs in a tar archive + /// Collect and store the logs in a tar archive. Store { #[clap(long, short = 'v')] /// Verbose output verbose: bool, #[clap(long, short = 'd')] - /// Path to destination directory. Optionally with the archive file name at the end. - /// An extension will be appended automatically depending on used compression. + /// Path to destination directory and, optionally, the archive file name. The extension will + /// be added automatically. destination: Option, }, - /// List logs which will be collected + /// List the logs to collect List, } diff --git a/rust/agama-cli/src/main.rs b/rust/agama-cli/src/main.rs index c715aff589..b8d5f8b4f1 100644 --- a/rust/agama-cli/src/main.rs +++ b/rust/agama-cli/src/main.rs @@ -28,8 +28,14 @@ use std::{ time::Duration, }; +/// Agama's command-line interface +/// +/// This program allows inspecting or changing Agama's configuration, handling installation +/// profiles, starting the installation, monitoring the process, etc. +/// +/// Please, use the "help" command to learn more. #[derive(Parser)] -#[command(name = "agama", version, about, long_about = None)] +#[command(name = "agama", about, long_about, max_term_width = 100)] struct Cli { #[command(subcommand)] pub command: Commands, diff --git a/rust/agama-cli/src/questions.rs b/rust/agama-cli/src/questions.rs index c73dc9d055..b99f4c96fb 100644 --- a/rust/agama-cli/src/questions.rs +++ b/rust/agama-cli/src/questions.rs @@ -5,20 +5,18 @@ use clap::{Args, Subcommand, ValueEnum}; #[derive(Subcommand, Debug)] pub enum QuestionsCommands { - /// Sets the mode for answering questions. - /// - /// It allows to decide if questions will be interactive or - /// if they should not block installation. + /// Set the mode for answering questions. Mode(ModesArgs), - /// Loads predefined answers to questions. + + /// Load predefined answers. /// - /// It allows to predefine answers for certain questions to skip - /// them in interactive mode or change answer in automatic mode. + /// It allows predifining answers for specific questions in order to skip them in interactive + /// mode or change the answer in automatic mode. /// - /// For more details and examples see official Agama documentation. + /// Please check Agama documentation for more details and examples: /// https://github.com/openSUSE/agama/blob/master/doc/questions.md Answers { - /// Local path to file with answers in YAML format + /// Path to a file containing the answers in YAML format. path: String, }, } @@ -31,7 +29,9 @@ pub struct ModesArgs { #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)] pub enum Modes { + /// Ask the user and block the installation. Interactive, + /// Do not block the installation. NonInteractive, } From b8738c4e3052711b1ff4d1ed824cc4c8d9d0068b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Imobach=20Gonz=C3=A1lez=20Sosa?= Date: Tue, 28 May 2024 11:43:13 +0100 Subject: [PATCH 3/3] fix(rust): fix a typo in the CLI docs --- rust/agama-cli/src/questions.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rust/agama-cli/src/questions.rs b/rust/agama-cli/src/questions.rs index b99f4c96fb..f066452e22 100644 --- a/rust/agama-cli/src/questions.rs +++ b/rust/agama-cli/src/questions.rs @@ -10,7 +10,7 @@ pub enum QuestionsCommands { /// Load predefined answers. /// - /// It allows predifining answers for specific questions in order to skip them in interactive + /// It allows predefining answers for specific questions in order to skip them in interactive /// mode or change the answer in automatic mode. /// /// Please check Agama documentation for more details and examples: