########################################################################## # Category/actions/arguments file # # # Except for general_arguments, this file contains 3 levels # as in this sample command line: # # yunohost monitor info --cpu --ram # ^ ^ ^ ^ # (script) | category | action | parameters # # # Above example will lead to the function 'monitor_info(args)' # in the file 'yunohost_monitor.py' with 'cpu' and 'ram' # stored in an 'args' dictionnary. # # Usage: # You can add a category at the first level, action at the second one, # and arguments at the third one. # If a connexion is needed for the action, don't forget to add it to # the action parameters (ldap, repo, dns or firewall). # # Documentation: # You can see all arguments settings at the argparse documentation: # http://docs.python.org/dev/library/argparse.html # #argparse.ArgumentParser.add_argument # # Don't forget to turn argument yaml style (setting: value) # ########################################################################## ############################# # Global parameters # ############################# _global: namespace: yunohost authentication: api: ldap_admin cli: null ############################# # User # ############################# user: category_help: Manage users and groups actions: ### user_list() list: action_help: List users api: GET /users arguments: --fields: help: fields to fetch (username, fullname, mail, mail-alias, mail-forward, mailbox-quota, groups, shell, home-path) nargs: "+" choices: - username - fullname - mail - mail-alias - mail-forward - mailbox-quota - groups - shell - home-path ### user_create() create: action_help: Create user api: POST /users arguments: username: help: The unique username to create extra: pattern: &pattern_username - !!str ^[a-z0-9][-a-z0-9_\.]*$ - "pattern_username" -F: full: --fullname help: The full name of the user. For example 'Camille Dupont' extra: ask: ask_fullname required: True pattern: &pattern_fullname - !!str ^([^\W_]{1,30}[ ,.'-]{0,3})+$ - "pattern_fullname" -p: full: --password help: User password extra: password: ask_password required: True pattern: &pattern_password - !!str ^.{3,}$ - "pattern_password" comment: good_practices_about_user_password -d: full: --domain help: Domain for the email address extra: pattern: &pattern_domain - !!str ^([^\W_A-Z]+([-]*[^\W_A-Z]+)*\.)+((xn--)?[^\W_]{2,})$ - "pattern_domain" autocomplete: &domains_list ynh_selector: domain list jq_selector: '.domains[]' use_cache: false -q: full: --mailbox-quota help: Mailbox size quota default: "0" metavar: "{SIZE|0}" extra: pattern: &pattern_mailbox_quota - !!str ^(\d+[bkMGT])|0$ - "pattern_mailbox_quota" -s: full: --loginShell help: The login shell used default: "/bin/bash" ### user_delete() delete: action_help: Delete user api: DELETE /users/ arguments: username: help: Username to delete extra: pattern: *pattern_username autocomplete: &users_list ynh_selector: user list --fields username jq_selector: '.users[].username' use_cache: false --purge: help: Purge user's home and mail directories action: store_true --force: help: Force user deletion action: store_true ### user_update() update: action_help: Update user informations api: PUT /users/ arguments: username: help: Username to update extra: autocomplete: *users_list -F: full: --fullname help: The full name of the user. For example 'Camille Dupont' extra: pattern: *pattern_fullname -m: full: --mail extra: pattern: &pattern_email - !!str ^[\w.-]+@([^\W_A-Z]+([-]*[^\W_A-Z]+)*\.)+((xn--)?[^\W_]{2,})$ - "pattern_email" -p: full: --change-password help: New password to set metavar: PASSWORD nargs: "?" const: 0 extra: pattern: *pattern_password comment: good_practices_about_user_password --add-mailforward: help: Mailforward addresses to add nargs: "*" metavar: MAIL extra: pattern: &pattern_email_forward - !!str ^[\w\+.-]+@([^\W_A-Z]+([-]*[^\W_A-Z]+)*\.)+((xn--)?[^\W_]{2,})$ - "pattern_email_forward" --remove-mailforward: help: Mailforward addresses to remove nargs: "*" metavar: MAIL --add-mailalias: help: Mail aliases to add nargs: "*" metavar: MAIL extra: pattern: *pattern_email --remove-mailalias: help: Mail aliases to remove nargs: "*" metavar: MAIL -q: full: --mailbox-quota help: Mailbox size quota metavar: "{SIZE|0}" extra: pattern: *pattern_mailbox_quota -s: full: --loginShell help: The login shell used default: "/bin/bash" ### user_info() info: action_help: Get user information api: GET /users/ arguments: username: help: Username or email to get information extra: autocomplete: *users_list ### user_export() export: action_help: Export users into CSV api: GET /users/export ### user_import() import: action_help: Import several users from CSV api: POST /users/import arguments: csvfile: help: "CSV file with columns username, firstname, lastname, password, mail, mailbox-quota, mail-alias, mail-forward, groups (separated by coma)" type: open extra: autocomplete: zsh_completion: _files -u: full: --update help: Update all existing users contained in the CSV file (by default existing users are ignored) action: store_true -d: full: --delete help: Delete all existing users that are not contained in the CSV file (by default existing users are kept) action: store_true subcategories: group: subcategory_help: Manage user groups actions: ### user_group_list() list: action_help: List existing groups api: GET /users/groups arguments: -f: full: --full help: Display all informations known about each groups action: store_true -p: full: --include-primary-groups help: Also display primary groups (each user has an eponym group that only contains itself) action: store_true default: false ### user_group_create() create: action_help: Create group api: POST /users/groups arguments: groupname: help: Name of the group to be created extra: pattern: &pattern_groupname - !!str ^[a-z0-9][-a-z0-9_\.]*$ - "pattern_groupname" ### user_group_delete() delete: action_help: Delete group api: DELETE /users/groups/ arguments: groupname: help: Name of the group to be deleted extra: pattern: *pattern_groupname autocomplete: &user_groups_list ynh_selector: user group list -s jq_selector: '.groups[]' use_cache: false ### user_group_info() info: action_help: Get information about a specific group api: GET /users/groups/ arguments: groupname: help: Name of the group to fetch info about extra: pattern: *pattern_groupname autocomplete: *user_groups_list ### user_group_add() add: action_help: Add users to group api: PUT /users/groups//add/ arguments: groupname: help: Name of the group to add user(s) to extra: pattern: *pattern_groupname autocomplete: *user_groups_list usernames: help: User(s) to add in the group nargs: "*" metavar: USERNAME extra: pattern: *pattern_username autocomplete: *users_list ### user_group_remove() remove: action_help: Remove users from group api: PUT /users/groups//remove/ arguments: groupname: help: Name of the group to remove user(s) from extra: pattern: *pattern_groupname autocomplete: *user_groups_list usernames: help: User(s) to remove from the group nargs: "*" metavar: USERNAME extra: pattern: *pattern_username autocomplete: *users_list ### user_group_add_mailalias() add-mailalias: action_help: Add mail aliases to group api: PUT /users/groups//aliases/ arguments: groupname: help: Name of the group to add user(s) to extra: pattern: *pattern_groupname autocomplete: *user_groups_list aliases: help: Mail aliases to add nargs: "+" metavar: MAIL extra: pattern: *pattern_email --force: help: Ignore warnings about special groups action: store_true ### user_group_remove_mailalias() remove-mailalias: action_help: Remove mail aliases to group api: DELETE /users/groups//aliases/ arguments: groupname: help: Name of the group to add user(s) to extra: pattern: *pattern_groupname autocomplete: *user_groups_list aliases: help: Mail aliases to remove nargs: "+" metavar: MAIL --force: help: Ignore warnings about special groups action: store_true permission: subcategory_help: Manage permissions actions: ### user_permission_list() list: action_help: List permissions and corresponding accesses api: GET /users/permissions arguments: apps: help: Apps to list permission for (all by default) nargs: "*" extra: autocomplete: &apps_list ynh_selector: app list jq_selector: '.apps[].id' use_cache: false -f: full: --full help: Display all info known about each permission, including the full user list of each group it is granted to. action: store_true ### user_permission_info() info: action_help: Get information about a specific permission api: GET /users/permissions/ arguments: permission: help: Name of the permission to fetch info about (use "yunohost user permission list" and "yunohost user permission -f" to see all the current permissions) extra: autocomplete: &permissions_list ynh_selector: user permission list jq_selector: '.permissions | keys[]' use_cache: false ### user_permission_update() update: action_help: Manage group or user permissions api: PUT /users/permissions/ arguments: permission: help: Permission to manage (e.g. mail or nextcloud or wordpress.editors) (use "yunohost user permission list" and "yunohost user permission -f" to see all the current permissions) extra: autocomplete: *permissions_list -l: full: --label help: Custom label for this app / permission -s: full: --show_tile help: Define if a tile will be shown in the user portal choices: - 'True' - 'False' -L: full: --logo help: File to use as logo for this app / permission. Only PNG are supported. type: argparse.FileType('rb') -d: full: --description help: Custom description for this app / permission -o: full: --order help: Order number to be used when displaying the tiles in the user portal. Default is 100 so set this to any low value for the tile to appear first, or higher value to appear last. type: int -H: full: --hide_from_public help: Mark the tile as to be hidden from the 'public app list' (if enabled). Useful for apps such as Nextcloud that need to be exposed to be publicly exposed for desktop/mobile client to be able to connect to, but not meant to be listed for visitors. choices: - "True" - "False" ## user_permission_add() add: action_help: Grant permission to group or user api: PUT /users/permissions//add/ arguments: permission: help: Permission to manage (e.g. mail or nextcloud or wordpress.editors) (use "yunohost user permission list" and "yunohost user permission -f" to see all the current permissions) extra: autocomplete: *permissions_list names: help: Group or usernames to grant this permission to nargs: "*" metavar: GROUP_OR_USER extra: pattern: *pattern_username autocomplete: &user_and_groups_list ynh_selector: user group list jq_selector: '[(.groups | keys), ([.groups[] | select(.members).members[]] | unique)] | add[]' use_cache: false ## user_permission_remove() remove: action_help: Revoke permission to group or user api: PUT /users/permissions//remove/ arguments: permission: help: Permission to manage (e.g. mail or nextcloud or wordpress.editors) (use "yunohost user permission list" and "yunohost user permission -f" to see all the current permissions) extra: autocomplete: *permissions_list names: help: Group or usernames to revoke this permission to nargs: "*" metavar: GROUP_OR_USER extra: pattern: *pattern_username autocomplete: *user_and_groups_list ## user_permission_ldapsync() ldapsync: action_help: Resynchronize permissions to LDAP from app settings. This is a purely technical command, only meant to be ran if you manually modified permission settings in app, which is absolutely not recommended. ssh: subcategory_help: Manage ssh access actions: ### user_ssh_keys_list() list-keys: action_help: Show user's authorized ssh keys api: GET /users/ssh/keys arguments: username: help: Username of the user extra: pattern: *pattern_username autocomplete: *users_list ### user_ssh_keys_add() add-key: action_help: Add a new authorized ssh key for this user api: POST /users/ssh/key arguments: username: help: Username of the user extra: pattern: *pattern_username autocomplete: *users_list key: help: The key to be added -c: full: --comment help: Optional comment about the key ### user_ssh_keys_remove() remove-key: action_help: Remove an authorized ssh key for this user api: DELETE /users/ssh/key arguments: username: help: Username of the user extra: pattern: *pattern_username autocomplete: *users_list key: help: The key to be removed ############################# # Domain # ############################# domain: category_help: Manage domains actions: ### domain_list() list: action_help: List domains api: GET /domains arguments: --exclude-subdomains: help: Filter out domains that are obviously subdomains of other declared domains action: store_true --tree: help: Display domains as a tree action: store_true --features: help: List only domains with features enabled (mail_in, mail_out) nargs: "*" ### domain_info() info: action_help: Get domain aggredated data api: GET /domains/ arguments: domain: help: Domain to check extra: pattern: *pattern_domain autocomplete: *domains_list ### domain_add() add: action_help: Create a custom domain api: POST /domains arguments: domain: help: Domain name to add extra: pattern: *pattern_domain --ignore-dyndns: help: If adding a DynDNS domain, only add the domain, without subscribing to the DynDNS service action: store_true --dyndns-recovery-password: metavar: PASSWORD nargs: "?" const: 0 help: If adding a DynDNS domain, subscribe to the DynDNS service with a password, used to later delete the domain extra: pattern: *pattern_password --install-letsencrypt-cert: help: If adding a subdomain of an already added domain, try to install a Let's Encrypt certificate action: store_true ### domain_remove() remove: action_help: Delete domains api: DELETE /domains/ arguments: domain: help: Domain to delete extra: pattern: *pattern_domain autocomplete: *domains_list -r: full: --remove-apps help: Remove apps installed on the domain action: store_true -f: full: --force help: Do not ask confirmation to remove apps action: store_true --ignore-dyndns: help: If removing a DynDNS domain, only remove the domain, without unsubscribing from the DynDNS service action: store_true --dyndns-recovery-password: metavar: PASSWORD nargs: "?" const: 0 help: If removing a DynDNS domain, unsubscribe from the DynDNS service with a password extra: pattern: *pattern_password ### domain_maindomain() main-domain: action_help: Check the current main domain, or change it deprecated_alias: - maindomain api: PUT /domains//main arguments: -n: full: --new-main-domain help: Change the current main domain extra: pattern: *pattern_domain autocomplete: *domains_list ### domain_url_available() url-available: hide_in_help: True action_help: Check availability of a web path api: GET /domain//urlavailable arguments: domain: help: The domain for the web path (e.g. your.domain.tld) extra: pattern: *pattern_domain autocomplete: *domains_list path: help: The path to check (e.g. /coffee) ### domain_action_run() action-run: hide_in_help: True action_help: Run domain action api: PUT /domain//actions/ arguments: domain: help: Domain name extra: autocomplete: *domains_list action: help: action id -a: full: --args help: Serialized arguments for action (i.e. "foo=bar&lorem=ipsum") subcategories: dyndns: subcategory_help: Subscribe and Update DynDNS Hosts actions: ### domain_dyndns_subscribe() subscribe: action_help: Subscribe to a DynDNS service arguments: domain: help: Domain to subscribe to the DynDNS service extra: pattern: *pattern_domain autocomplete: *domains_list -p: full: --recovery-password nargs: "?" const: 0 help: Password used to later recover the domain if needed extra: pattern: *pattern_password ### domain_dyndns_unsubscribe() unsubscribe: action_help: Unsubscribe from a DynDNS service arguments: domain: help: Domain to unsubscribe from the DynDNS service extra: pattern: *pattern_domain autocomplete: *domains_list required: True -p: full: --recovery-password nargs: "?" const: 0 help: Recovery password used to delete the domain extra: pattern: *pattern_password ### domain_dyndns_set_recovery_password() set-recovery-password: action_help: Set recovery password arguments: domain: help: Domain to set recovery password for extra: pattern: *pattern_domain autocomplete: *domains_list required: True -p: full: --recovery-password help: The new recovery password extra: password: ask_dyndns_recovery_password pattern: *pattern_password config: subcategory_help: Domain settings actions: ### domain_config_get() get: action_help: Display a domain configuration api: - GET /domains//config - GET /domains//config/ arguments: domain: help: Domain name extra: autocomplete: *domains_list key: help: A specific panel, section or a question identifier nargs: '?' -f: full: --full help: Display all details (meant to be used by the API) action: store_true -e: full: --export help: Only export key/values, meant to be reimported using "config set --args-file" action: store_true ### domain_config_set() set: action_help: Apply a new configuration api: PUT /domains//config/ arguments: domain: help: Domain name extra: autocomplete: *domains_list key: help: The question or form key nargs: '?' -v: full: --value help: new value -a: full: --args help: Serialized arguments for new configuration (i.e. "mail_in=0&mail_out=0") dns: subcategory_help: Manage domains DNS actions: ### domain_dns_conf() suggest: action_help: Generate sample DNS configuration for a domain api: - GET /domains//dns - GET /domains//dns/suggest arguments: domain: help: Target domain extra: pattern: *pattern_domain autocomplete: *domains_list ### domain_dns_push() push: action_help: Push DNS records to registrar api: POST /domains//dns/push arguments: domain: help: Domain name to push DNS conf for extra: pattern: *pattern_domain autocomplete: *domains_list -d: full: --dry-run help: Only display what's to be pushed action: store_true --force: help: Also update/remove records which were not originally set by Yunohost, or which have been manually modified action: store_true --purge: help: Delete all records action: store_true cert: subcategory_help: Manage domain certificates actions: ### certificate_status() status: action_help: List status of current certificates (all by default). api: - GET /domains//cert - GET /domains/*/cert arguments: domain_list: help: Domains to check nargs: "*" extra: autocomplete: *domains_list --full: help: Show more details action: store_true ### certificate_install() install: action_help: Install Let's Encrypt certificates for given domains (all by default). api: PUT /domains//cert arguments: domain_list: help: Domains for which to install the certificates nargs: "*" extra: autocomplete: *domains_list --force: help: Install even if current certificate is not self-signed action: store_true --no-checks: help: Does not perform any check that your domain seems correctly configured (DNS, reachability) before attempting to install. (Not recommended) action: store_true --self-signed: help: Install self-signed certificate instead of Let's Encrypt action: store_true ### certificate_renew() renew: action_help: Renew the Let's Encrypt certificates for given domains (all by default). api: PUT /domains//cert/renew arguments: domain_list: help: Domains for which to renew the certificates nargs: "*" extra: autocomplete: *domains_list --force: help: Ignore the validity threshold (15 days) action: store_true --email: help: Send an email to root with logs if some renewing fails action: store_true --no-checks: help: Does not perform any check that your domain seems correctly configured (DNS, reachability) before attempting to renew. (Not recommended) action: store_true ############################# # App # ############################# app: category_help: Manage apps actions: catalog: action_help: Show the catalog of installable application api: GET /apps/catalog arguments: -f: full: --full help: Display all details, including the app manifest and various other infos action: store_true -c: full: --with-categories help: Also return a list of app categories action: store_true -a: full: --with-antifeatures help: Also return a list of antifeatures categories action: store_true ### app_search() search: action_help: Search installable apps arguments: string: help: Return matching app name or description with "string" ### app_manifest() manifest: action_help: Return the manifest of a given app from the catalog, or from a remote git repo api: GET /apps/manifest arguments: app: help: Name, local path or git URL of the app to fetch the manifest of extra: autocomplete: &apps_catalog_list ynh_selector: app catalog jq_selector: '.apps | keys[]' use_cache: True -s: full: --with-screenshot help: Also return a base64 screenshot if any (API only) action: store_true extra: autocomplete: hide_in_help: True ### app_list() list: action_help: List installed apps api: GET /apps arguments: -f: full: --full help: Display all details, including the app manifest and various other infos action: store_true ### app_info() info: action_help: Show infos about a specific installed app api: GET /apps/ arguments: app: help: Specific app ID extra: autocomplete: *apps_list -f: full: --full help: Display all details, including the app manifest and various other infos action: store_true --with-pre-upgrade-notifications: help: Also fetch pre-upgrade notifications, if an upgrade is available (this is meant for the web API) action: store_true ### app_map() map: action_help: Show the mapping between urls and apps api: GET /apps/map arguments: -a: full: --app help: Specific app to map extra: autocomplete: *apps_list -r: full: --raw help: Return complete dict action: store_true -u: full: --user help: Allowed app map for a user extra: pattern: *pattern_username autocomplete: *users_list ### app_install() install: action_help: Install apps api: POST /apps arguments: app: help: Name, local path or git URL of the app to install extra: autocomplete: *apps_catalog_list -l: full: --label help: Custom name for the app -a: full: --args help: Serialized arguments for app script (i.e. "domain=domain.tld&path=/path&init_main_permission=visitors") -n: full: --no-remove-on-failure help: Debug option to avoid removing the app on a failed installation action: store_true -f: full: --force help: Do not ask confirmation if the app is not safe to use (low quality, experimental or 3rd party), or when the app displays a post-install notification action: store_true -i: full: --ignore-yunohost-version help: Attempt to install the app even if your YunoHost version is below the required one action: store_true ### app_remove() remove: action_help: Remove app api: DELETE /apps/ arguments: app: help: App to remove extra: autocomplete: *apps_list -p: full: --purge help: Also remove all application data action: store_true ### app_upgrade() upgrade: action_help: Upgrade app api: PUT /apps//upgrade arguments: app: help: App(s) to upgrade (default all) nargs: "*" extra: autocomplete: *apps_list -u: full: --url help: Git url to fetch for upgrade -f: full: --file help: Folder or tarball for upgrade -F: full: --force help: Force the update, even though the app is up to date action: store_true -b: full: --no-safety-backup help: Disable the safety backup during upgrade action: store_true -c: full: --continue-on-failure help: Continue to upgrade apps even if one or more upgrade failed action: store_true -i: full: --ignore-yunohost-version help: Attempt to upgrade the app even if your YunoHost version is below the required one action: store_true ### app_change_url() change-url: action_help: Change app's URL api: PUT /apps//changeurl arguments: app: help: Target app instance name extra: autocomplete: *apps_list -d: full: --domain help: New app domain on which the application will be moved extra: ask: ask_new_domain pattern: *pattern_domain required: True autocomplete: *domains_list -p: full: --path help: New path at which the application will be moved extra: ask: ask_new_path required: True ### app_setting() setting: action_help: Set or get an app setting value api: GET /apps//settings arguments: app: help: App ID extra: autocomplete: *apps_list key: help: Key to get/set -v: full: --value help: Value to set -d: full: --delete help: Delete the key action: store_true ### app_shell() shell: action_help: Open an interactive shell with the app environment already loaded # Here we set a GET only not to lock the command line. There is no actual API endpoint for app_shell() api: GET /apps//shell arguments: app: help: App ID extra: autocomplete: *apps_list ### app_db() db: action_help: Open an interactive database client prompt for the app api: GET /apps//db arguments: app: help: App ID extra: autocomplete: *apps_list ### app_register_url() register-url: hide_in_help: True action_help: Book/register a web path for a given app arguments: app: help: App which will use the web path extra: autocomplete: *apps_list domain: help: The domain on which the app should be registered (e.g. your.domain.tld) extra: autocomplete: *domains_list path: help: The path to be registered (e.g. /coffee) ### app_makedefault() makedefault: hide_in_help: True action_help: Redirect domain root to an app api: PUT /apps//default arguments: app: help: App name to put on domain root extra: autocomplete: *apps_list -d: full: --domain help: Specific domain to put app on (the app domain by default) extra: autocomplete: *domains_list -u: full: --undo help: Undo redirection action: store_true ### app_dismiss_notification dismiss-notification: hide_in_help: True action_help: Dismiss post_install or post_upgrade notification api: PUT /apps//dismiss_notification/ arguments: app: help: App ID to dismiss notification for extra: autocomplete: *apps_list name: help: Notification name, either post_install or post_upgrade choices: - post_install - post_upgrade ### app_ssowatconf() ssowatconf: action_help: Regenerate SSOwat configuration file ### app_change_label() change-label: action_help: Change app label api: PUT /apps//label arguments: app: help: App ID extra: autocomplete: *apps_list new_label: help: New app label subcategories: action: subcategory_help: Handle apps actions actions: ### app_action_list() list: action_help: List app actions api: GET /apps//actions arguments: app: help: App name extra: autocomplete: *apps_list ### app_action_run() run: action_help: Run app action api: PUT /apps//actions/ arguments: app: help: App name extra: autocomplete: *apps_list action: help: action id -a: full: --args help: Serialized arguments for app script (i.e. "domain=domain.tld&path=/path") config: subcategory_help: Applications configuration panel actions: ### app_config_get() get: action_help: Display an app configuration api: - GET /apps//config - GET /apps//config/ arguments: app: help: App name extra: autocomplete: *apps_list key: help: A specific panel, section or a question identifier nargs: '?' -f: full: --full help: Display all details (meant to be used by the API) action: store_true -e: full: --export help: Only export key/values, meant to be reimported using "config set --args-file" action: store_true --core: help: Get the 'core' config for this app, such as permissions stuff. This option is only meant for API. action: store_true ### app_config_set() set: action_help: Apply a new configuration api: PUT /apps//config/ arguments: app: help: App name extra: autocomplete: *apps_list key: help: The question or panel key nargs: '?' -v: full: --value help: new value -a: full: --args help: Serialized arguments for new configuration (i.e. "domain=domain.tld&path=/path") -f: full: --args-file help: YAML or JSON file with key/value couples type: open --core: help: Set the 'core' config for this app, such as permissions stuff. This option is only meant for API. action: store_true ############################# # Backup # ############################# backup: category_help: Manage backups actions: ### backup_create() create: action_help: Create a backup local archive. If neither --apps or --system are given, this will backup all apps and all system parts. If only --apps if given, this will only backup apps and no system parts. Similarly, if only --system is given, this will only backup system parts and no apps. api: POST /backups arguments: -n: full: --name help: Name of the backup archive extra: pattern: &pattern_backup_archive_name - !!str ^[\w\-\._]{1,50}(?/restore arguments: name: help: Name or path of the backup archive extra: autocomplete: &backups_list ynh_selector: backup list jq_selector: '.archives[]' use_cache: false --system: help: List of system parts to restore (or all if none is given) nargs: "*" --apps: help: List of application names to restore (or all if none is given) nargs: "*" extra: autocomplete: *apps_list --force: help: Force restauration on an already installed system action: store_true --no-remove-on-failure: help: For app only, debug option to avoid removing the app on a failed restore action: store_true ### backup_list() list: action_help: List available local backup archives api: GET /backups arguments: -i: full: --with-info help: Show backup information for each archive action: store_true -H: full: --human-readable help: Print sizes in human readable format action: store_true ### backup_info() info: action_help: Show info about a local backup archive api: GET /backups/ arguments: name: help: Name or path of the backup archive extra: autocomplete: *backups_list -d: full: --with-details help: Show additional backup information action: store_true -H: full: --human-readable help: Print sizes in human readable format action: store_true ### backup_download() download: hide_in_help: True action_help: (API only) Request to download the file api: GET /backups//download arguments: name: help: Name of the local backup archive ### backup_delete() delete: action_help: Delete a backup archive api: DELETE /backups/ arguments: name: help: Name of the archive to delete extra: pattern: *pattern_backup_archive_name autocomplete: *backups_list ############################# # Settings # ############################# settings: category_help: Manage YunoHost global settings actions: ### settings_list() list: action_help: list all entries of the settings api: GET /settings arguments: -f: full: --full help: Display all details (meant to be used by the API) action: store_true ### settings_get() get: action_help: get an entry value in the settings api: GET /settings/ arguments: key: help: Settings key extra: autocomplete: &settings_list ynh_selector: settings list jq_selector: '. | keys[]' use_cache: false -f: full: --full help: Display all details (meant to be used by the API) action: store_true -e: full: --export help: Only export key/values, meant to be reimported using "config set --args-file" action: store_true ### settings_set() set: action_help: set an entry value in the settings api: PUT /settings/ arguments: key: help: The question or form key nargs: '?' extra: autocomplete: *settings_list -v: full: --value help: new value -a: full: --args help: Serialized arguments for new configuration (i.e. "mail_in=0&mail_out=0") ### settings_reset_all() reset-all: action_help: reset all settings to their default value api: DELETE /settings ### settings_reset() reset: action_help: set an entry value to its default one api: DELETE /settings/ arguments: key: help: Settings key extra: autocomplete: *settings_list ############################# # Service # ############################# service: category_help: Manage services actions: ### service_add() add: action_help: Add a service arguments: name: help: Service name to add -d: full: --description help: Description of the service -l: full: --log help: Absolute path to log file to display nargs: "+" extra: autocomplete: zsh_completion: _files --test_status: help: Specify a custom bash command to check the status of the service. Note that it only makes sense to specify this if the corresponding systemd service does not return the proper information already. --test_conf: help: Specify a custom bash command to check if the configuration of the service is valid or broken, similar to nginx -t. --needs_exposed_ports: help: A list of ports that needs to be publicly exposed for the service to work as intended. nargs: "+" type: int metavar: PORT -n: full: --need_lock help: Use this option to prevent deadlocks if the service does invoke yunohost commands. action: store_true ### service_remove() remove: action_help: Remove a service arguments: name: help: Service name to remove extra: autocomplete: &services_list ynh_selector: service status jq_selector: '. | keys[]' use_cache: false ### service_start() start: action_help: Start one or more services api: PUT /services//start arguments: names: help: Service name to start nargs: "+" metavar: NAME extra: autocomplete: *services_list ### service_stop() stop: action_help: Stop one or more services api: PUT /services//stop arguments: names: help: Service name to stop nargs: "+" metavar: NAME extra: autocomplete: *services_list ### service_reload() reload: action_help: Reload one or more services arguments: names: help: Service name to reload nargs: "+" metavar: NAME extra: autocomplete: *services_list ### service_restart() restart: action_help: Restart one or more services. If the services are not running yet, they will be started. api: PUT /services//restart arguments: names: help: Service name to restart nargs: "+" metavar: NAME extra: autocomplete: *services_list ### service_reload_or_restart() reload_or_restart: action_help: Reload one or more services if they support it. If not, restart them instead. If the services are not running yet, they will be started. arguments: names: help: Service name to reload or restart nargs: "+" metavar: NAME extra: autocomplete: *services_list ### service_enable() enable: action_help: Enable one or more services api: PUT /services//enable arguments: names: help: Service name to enable nargs: "+" metavar: NAME extra: autocomplete: *services_list ### service_disable() disable: action_help: Disable one or more services api: PUT /services//disable arguments: names: help: Service name to disable nargs: "+" metavar: NAME extra: autocomplete: *services_list ### service_status() status: action_help: Show status information about one or more services (all by default) api: - GET /services - GET /services/ arguments: names: help: Service name to show nargs: "*" metavar: NAME extra: autocomplete: *services_list ### service_log() log: action_help: Log every log files of a service api: GET /services//log arguments: name: help: Service name to log extra: autocomplete: *services_list -n: full: --number help: Number of lines to display default: 50 type: int ############################# # Firewall # ############################# firewall: category_help: Manage firewall rules actions: ### firewall_list() list: action_help: List all firewall rules api: GET /firewall arguments: -r: full: --raw help: Return the complete YAML dict action: store_true -p: full: --protocol help: "If not raw, protocol type to list (tcp/udp)" choices: - tcp - udp nargs: "?" default: tcp -f: full: --forwarded help: If not raw, list UPnP forwarded ports instead of open ports action: store_true ### firewall_is_open() is-open: action_help: Returns whether the port is open or not. api: GET /firewall// arguments: port: help: Port or range of ports to check extra: pattern: &pattern_port_or_range - !!str ((^|(?!\A):)([0-9]{1,4}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])){1,2}?$ - "pattern_port_or_range" -p: full: --protocol help: "Protocol type (tcp/udp)" choices: - tcp - udp default: tcp ### firewall_open() open: action_help: Allow connections on a port api: PUT /firewall//open/ arguments: port: help: Port or range of ports to open extra: pattern: *pattern_port_or_range -p: full: --protocol help: "Protocol type (tcp/udp)" choices: - tcp - udp default: tcp comment: help: A reason for the port to be open (like the app's name) default: "" --upnp: help: Add forwarding of this port with UPnP action: store_true --no-reload: help: Do not reload firewall rules action: store_true ### firewall_close() close: action_help: Disallow connections on a port api: PUT /firewall//close/ arguments: port: help: Port or range of ports to close extra: pattern: *pattern_port_or_range -p: full: --protocol help: "Protocol type (tcp/udp)" choices: - tcp - udp default: tcp --upnp-only: help: Only remove forwarding of this port with UPnP action: store_true --no-reload: help: Do not reload firewall rules action: store_true ### firewall_delete() delete: action_help: Unregister a port from YunoHost api: PUT /firewall//delete/ arguments: port: help: Port or range of ports to delete extra: pattern: *pattern_port_or_range -p: full: --protocol help: "Protocol type (tcp/udp)" choices: - tcp - udp default: tcp --no-reload: help: Do not reload firewall rules action: store_true ### firewall_allow() allow: action_help: Allow connections on a port api: PUT /firewall//allow/ arguments: protocol: help: "Protocol type to allow (TCP/UDP/Both)" choices: - TCP - UDP - Both default: TCP port: help: Port or range of ports to open extra: pattern: *pattern_port_or_range -4: full: --ipv4-only help: Only add a rule for IPv4 connections action: store_true -6: full: --ipv6-only help: Only add a rule for IPv6 connections action: store_true --no-upnp: help: Do not add forwarding of this port with UPnP action: store_true --no-reload: help: Do not reload firewall rules action: store_true ### firewall_disallow() disallow: action_help: Disallow connections on a port api: PUT /firewall//disallow/ arguments: protocol: help: "Protocol type to allow (TCP/UDP/Both)" choices: - TCP - UDP - Both default: TCP port: help: Port or range of ports to close extra: pattern: *pattern_port_or_range -4: full: --ipv4-only help: Only remove the rule for IPv4 connections action: store_true -6: full: --ipv6-only help: Only remove the rule for IPv6 connections action: store_true --upnp-only: help: Only remove forwarding of this port with UPnP action: store_true --no-reload: help: Do not reload firewall rules action: store_true ### firewall_upnp() upnp: action_help: Manage port forwarding using UPnP api: PUT /firewall/upnp/ arguments: action: choices: - enable - disable - status nargs: "?" default: status --no-refresh: help: Do not refresh port forwarding action: store_true ### firewall_reload() reload: action_help: Reload all firewall rules arguments: --skip-upnp: help: Do not refresh port forwarding using UPnP action: store_true ### firewall_stop() stop: action_help: Remove all the firewall rules ############################# # DynDNS # ############################# dyndns: category_help: Subscribe and Update DynDNS Hosts ( deprecated, use 'yunohost domain dyndns' instead ) actions: ### dyndns_subscribe() subscribe: action_help: Subscribe to a DynDNS service deprecated: true arguments: -d: full: --domain help: Full domain to subscribe with ( deprecated, use 'yunohost domain dyndns subscribe' instead ) extra: pattern: *pattern_domain autocomplete: *domains_list -p: full: --recovery-password nargs: "?" const: 0 help: Password used to later recover the domain if needed extra: pattern: *pattern_password ### dyndns_update() update: action_help: Update IP on DynDNS platform arguments: -d: full: --domain help: Full domain to update extra: pattern: *pattern_domain autocomplete: *domains_list -f: full: --force help: Force the update (for debugging only) action: store_true -D: full: --dry-run help: Only display the generated zone action: store_true ############################# # Tools # ############################# tools: category_help: Specific tools actions: ### tools_rootpw() rootpw: action_help: Change root password api: PUT /rootpw arguments: -n: full: --new-password extra: password: ask_new_admin_password pattern: *pattern_password required: True comment: good_practices_about_admin_password ### tools_maindomain() maindomain: action_help: Check the current main domain, or change it arguments: -n: full: --new-main-domain help: Change the current main domain extra: pattern: *pattern_domain autocomplete: *domains_list ### tools_postinstall() postinstall: action_help: YunoHost post-install api: POST /postinstall authentication: # We need to be able to run the postinstall without being authenticated, otherwise we can't run the postinstall api: null arguments: -d: full: --domain help: YunoHost main domain extra: ask: ask_main_domain pattern: *pattern_domain required: True autocomplete: *domains_list -u: full: --username help: Username for the first (admin) user. For example 'camille' extra: ask: ask_admin_username pattern: *pattern_username required: True autocomplete: *users_list -F: full: --fullname help: The full name for the first (admin) user. For example 'Camille Dupont' extra: ask: ask_admin_fullname required: True pattern: *pattern_fullname -p: full: --password help: YunoHost admin password extra: password: ask_new_admin_password pattern: *pattern_password required: True comment: good_practices_about_admin_password --ignore-dyndns: help: If adding a DynDNS domain, only add the domain, without subscribing to the DynDNS service action: store_true --dyndns-recovery-password: metavar: PASSWORD nargs: "?" const: 0 help: If adding a DynDNS domain, subscribe to the DynDNS service with a password, used to later recover the domain if needed extra: pattern: *pattern_password --force-diskspace: help: Use this if you really want to install YunoHost on a setup with less than 10 GB on the root filesystem action: store_true --i-have-read-terms-of-services: help: Automatically reply to the terms of services prompt, for example for non-interactive installations action: store_true update_norefresh: # This exists mainly for the API, such that there's an explicit read-only (GET) route # vs the old/regular/legacy(?)/ambiguous PUT /update route ... hide_in_help: True action_help: List available system/apps updates (without refreshing caches) api: GET /update ### tools_update() update: action_help: YunoHost update api: PUT /update/ arguments: target: help: What to update, "apps" (application catalog) or "system" (fetch available package upgrades, equivalent to apt update), "all" for both choices: - apps - system - all nargs: "?" metavar: TARGET default: all --no-refresh: help: Does not run apt update or fetch the apps catalog, only list upgradable packages and apps action: store_true ### tools_upgrade() upgrade: action_help: YunoHost upgrade api: PUT /upgrade/ arguments: target: help: What to upgrade, either "apps" (all apps) or "system" (all system packages) choices: - apps - system nargs: "?" ### tools_shell() shell: action_help: Launch a development shell arguments: -c: help: python command to execute full: --command ### tools_basic_space_cleanup() basic-space-cleanup: action_help: Basic space cleanup (apt, journalctl, system and YunoHost logs, ...) ### tools_shutdown() shutdown: action_help: Shutdown the server api: PUT /shutdown arguments: -f: help: skip the shutdown confirmation full: --force action: store_true ### tools_reboot() reboot: action_help: Reboot the server api: PUT /reboot arguments: -f: help: skip the reboot confirmation full: --force action: store_true ### tools_regen_conf() regen-conf: action_help: Regenerate the configuration file(s) api: - PUT /regenconf - PUT /regenconf/ arguments: names: help: Categories to regenerate configuration of (all by default) nargs: "*" metavar: NAME -d: full: --with-diff help: Show differences in case of configuration changes action: store_true -f: full: --force help: Override all manual modifications in configuration files action: store_true -n: full: --dry-run help: Show what would have been regenerated action: store_true -p: full: --list-pending help: List pending configuration files and exit action: store_true ### tools_versions() versions: action_help: Display YunoHost's packages versions api: GET /versions subcategories: migrations: subcategory_help: Manage migrations actions: ### tools_migrations_list() list: action_help: List migrations api: GET /migrations arguments: --pending: help: list only pending migrations action: store_true --done: help: list only migrations already performed action: store_true ### tools_migrations_run() run: action_help: Run migrations api: - PUT /migrations - PUT /migrations/ deprecated_alias: - migrate arguments: targets: help: Migrations to run (all pendings by default) nargs: "*" extra: autocomplete: &migrations_list ynh_selector: tools migrations list jq_selector: '.migrations[].id' use_cache: false --skip: help: Skip specified migrations (to be used only if you know what you are doing) action: store_true --force-rerun: help: Re-run already-ran specified migration (to be used only if you know what you are doing) action: store_true --auto: help: Automatic mode, won't run manual migrations (to be used only if you know what you are doing) action: store_true --accept-disclaimer: help: Accept disclaimers of migrations (please read them before using this option) action: store_true ### tools_migrations_state() state: action_help: Show current migrations state ############################# # Hook # ############################# hook: category_help: Manage hooks actions: ### hook_add() add: action_help: Store hook script to filesystem arguments: app: help: App to link with extra: autocomplete: *apps_list file: help: Script to add extra: autocomplete: zsh_completion: _files ### hook_remove() remove: action_help: Remove hook scripts from filesystem arguments: app: help: Scripts related to app will be removed extra: autocomplete: *apps_list ### hook_info() info: hide_in_help: false action_help: Get information about a given hook arguments: action: help: Action name choices: &hook_action_choices - post_user_create - post_user_delete - post_user_update - post_app_addaccess - post_app_removeaccess - post_domain_add - post_domain_remove - post_cert_update - custom_dns_rules - post_app_change_url - post_app_upgrade - post_app_install - post_app_remove - backup - restore - backup_method - post_iptable_rules - conf_regen name: help: Hook name extra: autocomplete: &hooks_list_case ynh_selector: hook list jq_selector: '.hooks[]' depends: previous use_cache: true ### hook_list() list: action_help: List available hooks for an action api: GET /hooks/ arguments: action: help: Action name choices: *hook_action_choices -l: full: --list-by help: Property to list hook by choices: - name - priority - folder default: name -i: full: --show-info help: Show hook information action: store_true ### hook_callback() callback: hide_in_help: True action_help: Execute all scripts binded to an action arguments: action: help: Action name choices: *hook_action_choices -n: full: --hooks help: List of hooks names to execute nargs: "*" -a: full: --args help: Ordered list of arguments to pass to the scripts nargs: "*" -d: full: --chdir help: The directory from where the scripts will be executed ### hook_exec() exec: hide_in_help: True action_help: Execute hook from a file with arguments arguments: path: help: Path of the script to execute extra: autocomplete: zsh_completion: _files -a: full: --args help: Ordered list of arguments to pass to the script nargs: "*" --raise-on-error: help: Raise if the script returns a non-zero exit code action: store_true -d: full: --chdir help: The directory from where the script will be executed ############################# # Log # ############################# log: category_help: Manage debug logs actions: ### log_list() list: action_help: List logs api: GET /logs arguments: -l: full: --limit help: Maximum number of operations to list (default to 50) type: int default: 50 -d: full: --with-details help: Show additional infos (e.g. operation success) but may significantly increase command time. Consider using --limit in combination with this. action: store_true -s: full: --with-suboperations help: Include metadata about operations that are not the main operation but are sub-operations triggered by another ongoing operation... (e.g. initializing groups/permissions when installing an app) action: store_true ### log_show() show: action_help: Display a log content api: GET /logs/ deprecated_alias: - display arguments: path: help: Log file which to display the content extra: autocomplete: &logs_list ynh_selector: log list jq_selector: '.operation[].name' use_cache: false -n: full: --number help: Number of lines to display default: 50 type: int --share: help: (Deprecated, see yunohost log share) Share the full log using yunopaste action: store_true -i: full: --filter-irrelevant help: Do not show some lines deemed not relevant (like set +x or helper argument parsing) action: store_true -s: full: --with-suboperations help: Include metadata about sub-operations of this operation... (e.g. initializing groups/permissions when installing an app) action: store_true ### log_share() share: action_help: Share the full log on yunopaste (alias to show --share) api: GET /logs//share arguments: path: help: Log file to share extra: autocomplete: *logs_list ############################# # Diagnosis # ############################# diagnosis: category_help: Look for possible issues on the server actions: list: action_help: List diagnosis categories api: GET /diagnosis/categories show: action_help: Show most recents diagnosis results api: GET /diagnosis arguments: categories: help: Diagnosis categories to display (all by default) nargs: "*" extra: autocomplete: &diagnosis_list ynh_selector: diagnosis list jq_selector: '.categories[]' use_cache: false --full: help: Display additional information action: store_true --issues: help: Only display issues action: store_true --share: help: Share the logs using yunopaste action: store_true --human-readable: help: Show a human-readable output action: store_true get: action_help: Low-level command to fetch raw data and status about a specific diagnosis test api: GET /diagnosis/ arguments: category: help: Diagnosis category to fetch results from extra: autocomplete: *diagnosis_list item: help: "List of criteria describing the test. Must correspond exactly to the 'meta' infos in 'yunohost diagnosis show'" metavar: CRITERIA nargs: "*" run: action_help: Run diagnosis api: PUT /diagnosis/run arguments: categories: help: Diagnosis categories to run (all by default) nargs: "*" extra: autocomplete: *diagnosis_list --force: help: Ignore the cached report even if it is still 'fresh' action: store_true --except-if-never-ran-yet: help: Don't run anything if diagnosis never ran yet ... (this is meant to be used by the webadmin) action: store_true --email: help: Send an email to root with issues found (this is meant to be used by cron job) action: store_true ignore: action_help: Configure some diagnosis results to be ignored and therefore not considered as actual issues api: PUT /diagnosis/ignore arguments: --filter: help: "Add a filter. The first element should be a diagnosis category, and other criterias can be provided using the infos from the 'meta' sections in 'yunohost diagnosis show'. For example: 'dnsrecords domain=yolo.test category=mail'" nargs: "*" metavar: CRITERIA --list: help: List active ignore filters action: store_true unignore: action_help: Configure some diagnosis results to be unignored and therefore considered as actual issues api: PUT /diagnosis/unignore arguments: --filter: help: Remove a filter (it should be an existing filter as listed with "ignore --list") nargs: "*" metavar: CRITERIA ############################# # Storage # ############################# storage: category_help: Manage hard-drives, filesystem, pools subcategories: disk: subcategory_help: Manage et get infos about hard-drives actions: # storage_disks_list list: action_help: List hard-drives currently attached to this system optionnaly with infos api: GET /storage/disk/list arguments: -H: full: --human-readable help: Print informations in a human-readable format action: store_true --human-readable-size: help: Print sizes in a human-readable format action: store_true -i: full: --with-info help: Get all informations for each archive action: store_true # storage_disks_info info: action_help: Get hard-drive information api: GET /storage/disk/info/ arguments: -H: full: --human-readable help: Print informations in a human-readable format action: store_true --human-readable-size: help: Print sizes in a human-readable format action: store_true