doc/packaging_apps_arguments_format.md

YunoHost Arguments Format

In YunoHost application developpement there are several places where you end up writting questions for your user like in the manifest.json/toml, the config_panel.json/toml or actions.json/toml.

This page documents this format and all available kind of questions you can ask your user. Unless it's stated otherwise, this format applies to everyplace it's usable (for now: installation arguments in manifest.json/toml, config_panel.json/toml and actions.json/toml)

YunoHost arguments general format

The general format for an argument looks like this in toml:

[maybe.some.stuff.before.the_name]
type = "one_of_the_available_type"
ask.en = "the question in english"
ask.fr = "the question in french"
help.en = "some help text in english" # optional
help.fr = "some help text in french" # optional
example = "an example value" # optional
default = "some stuff" # optional, not available for all types
optional = true # optional, will skip if not answered

And in json:

{
    "name": "the_name",
    "type": "one_of_the_available_type",  // "sting" is not specified
    "ask": {
        "en": "the question in english",
        "fr": "the question in french"
    },
    "help": {
        "en": "some help text in english",
        "fr": "some help text in french"
    }
    "default", "some stuff", // optional, not available for all types
    "example": "an example value", // optional
    "optional": true, // optional, will skip if not answered
},

All avaiable types

string

This one is the simpliest one and is the default type if you don't specify one.

Example in toml:

[maybe.some.stuff.before.the_name]
type = "string"  # optional
ask.en = "the question in english"
ask.fr = "the question in french"
example = "an example value"  # optional
default = "some stuff" # optional

And in json:

{
    "name": "the_name",
    "type": "string",  // optional
    "ask": {
        "en": "the question in english",
        "fr": "the question in french"
    },
    "default": "some stuff", // optional
    "example": "an example value"
},

string with choices

Like string except the user needs to chose in a list of specifics strings.

Example in toml:

[maybe.some.stuff.before.the_name]
type = "string"
ask.en = "the question in english"
ask.fr = "the question in french"
example = "an example value"  # optional
choices = ["fr", "en"]
default = "en" # optional

And in json:

{
    "name": "the_name",
    "type": "string",
    "ask": {
        "en": "the question in english",
        "fr": "the question in french"
    },
    "example": "an example value",
    "choices": ["fr", "en"],
    "default": "en" // optional
},

domain

This type will ask the user to chose one of the domains of their YunoHost instance.

Example in toml:

[maybe.some.stuff.before.the_name]
type = "domain"
ask.en = "the question in english"
ask.fr = "the question in french"

And in json:

{
    "name": "the_name",
    "type": "domain",
    "ask": {
        "en": "the question in english",
        "fr": "the question in french"
    }
},

Path

This type will ask the user to chose an url path (generally to happen it to a domain) like "/path/to/my/app"

Example in toml:

[maybe.some.stuff.before.the_name]
type = "path"
ask.en = "the question in english"
ask.fr = "the question in french"
default = "/my_app"

And in json:

{
    "name": "the_name",
    "type": "path",
    "ask": {
        "en": "the question in english",
        "fr": "the question in french"
    },
    "default": "/my_app"
},

User

This type will ask the user to select a user in the list of users in their YunoHost installation. Generally this is used to select who is going to be the admin or who is going to have access to this application.

Example in toml:

[maybe.some.stuff.before.the_name]
type = "user"
ask.en = "the question in english"
ask.fr = "the question in french"

And in json:

{
    "name": "the_name",
    "type": "user",
    "ask": {
        "en": "the question in english",
        "fr": "the question in french"
    }
},

Password

This type will ask the user to input a password. This is generally used to input the password for creating an account on the application.

In CLI it will behave like any password query and won't print any character on type (not "***...") for security reasons.

Example in toml:

[maybe.some.stuff.before.the_name]
type = "password"
ask.en = "the question in english"
ask.fr = "the question in french"

And in json:

{
    "name": "the_name",
    "type": "password",
    "ask": {
        "en": "the question in english",
        "fr": "the question in french"
    }
},

Boolean

This type will ask the user to answer true or false to a question.

Example in toml:

[maybe.some.stuff.before.the_name]
type = "boolean"
ask.en = "the question in english"
ask.fr = "the question in french"
default = true

And in json:

{
    "name": "the_name",
    "type": "boolean",
    "ask": {
        "en": "the question in english",
        "fr": "the question in french"
    },
    "default": true
},

App

This type will ask the user to select an application in the list of installed application on their YunoHost.

Example in toml:

[maybe.some.stuff.before.the_name]
type = "app"
ask.en = "the question in english"
ask.fr = "the question in french"

And in json:

{
    "name": "the_name",
    "type": "app",
    "ask": {
        "en": "the question in english",
        "fr": "the question in french"
    }
},

display_text

This is a special type that allows the application packager to write some text that will be simply displayed. This is useful to provide more context.

[maybe.some.stuff.before.the_name]
type = "display_text"
ask.en = "the text in english"
ask.fr = "the text in french"

And in json:

{
    "name": "the_name",
    "type": "display_text",
    "ask": {
        "en": "the text in english",
        "fr": "the text in french"
    }
},