CLI: ara API client

Installing ara provides an ara command line interface client in order to query API servers from shell scripts or from the terminal.

ara

$ ara --help
usage: ara [--version] [-v | -q] [--log-file LOG_FILE] [-h] [--debug]

A CLI client to query ARA API servers

optional arguments:
  --version            show program's version number and exit
  -v, --verbose        Increase verbosity of output. Can be repeated.
  -q, --quiet          Suppress output except warnings and errors.
  --log-file LOG_FILE  Specify a file to log output. Disabled by default.
  -h, --help           Show help message and exit.
  --debug              Show tracebacks on errors.

Commands:
  complete       print bash completion command (cliff)
  expire         Expires objects that have been in the running state for too long 
  help           print detailed help for another command (cliff)
  host delete    Deletes the specified host and associated resources 
  host list      Returns a list of hosts based on search queries 
  host show      Returns a detailed view of a specified host 
  play delete    Deletes the specified play and associated resources 
  play list      Returns a list of plays based on search queries 
  play show      Returns a detailed view of a specified play 
  playbook delete  Deletes the specified playbook and associated resources 
  playbook list  Returns a list of playbooks based on search queries 
  playbook prune  Deletes playbooks beyond a specified age in days 
  playbook show  Returns a detailed view of a specified playbook 
  record delete  Deletes the specified record and associated resources 
  record list    Returns a list of records based on search queries 
  record show    Returns a detailed view of a specified record 
  result delete  Deletes the specified result and associated resources 
  result list    Returns a list of results based on search queries 
  result show    Returns a detailed view of a specified result 
  task delete    Deletes the specified task and associated resources 
  task list      Returns a list of tasks based on search queries 
  task show      Returns a detailed view of a specified task

ara expire

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara expire --help
usage: ara expire [-h] [--client <client>] [--server <url>]
                  [--timeout <seconds>] [--username <username>]
                  [--password <password>] [--insecure] [--hours HOURS]
                  [--order <order>] [--limit <limit>] [--confirm]

Expires objects that have been in the running state for too long

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --hours HOURS         Expires objects that have been running state for this
                        many hours (default: 24)
  --order <order>       Orders objects by a field ('id', 'created', 'updated',
                        'started', 'ended')
                        Defaults to 'started' descending so the oldest objects
                        would be expired first.
                        The order can be reversed by using '-': ara expire
                        --order=-started
  --limit <limit>       Only expire the first <limit> determined by the
                        ordering. Defaults to ARA_CLI_LIMIT or 200.
  --confirm             Confirm expiration of objects, otherwise runs without
                        expiring any objects

Examples:

# Return which objects would be expired by ommitting --confirm
ara expire

# Expire running objects without updates faster than the default
ara expire --hours 4 --confirm

ara playbook list

$ ara playbook list --help
usage: ara playbook list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                         [--quote {all,minimal,none,nonnumeric}] [--noindent]
                         [--max-width <integer>] [--fit-width] [--print-empty]
                         [--sort-column SORT_COLUMN] [--client <client>]
                         [--server <url>] [--timeout <seconds>]
                         [--username <username>] [--password <password>]
                         [--insecure] [--label <label>] [--name <name>]
                         [--path <path>] [--status <status>] [--long]
                         [--order <order>] [--limit <limit>]

Returns a list of playbooks based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --label <label>       List playbooks matching the provided label
  --name <name>         List playbooks matching the provided name (full or
                        partial)
  --path <path>         List playbooks matching the provided path (full or
                        partial)
  --status <status>     List playbooks matching a specific status
                        ('completed', 'running', 'failed')
  --long                Don't truncate paths and include additional fields:
                        name, plays, files, records
  --order <order>       Orders playbooks by a field ('id', 'created',
                        'updated', 'started', 'ended', 'duration')
                        Defaults to '-started' descending so the most recent
                        playbook is at the top.
                        The order can be reversed by omitting the '-': ara
                        playbook list --order=started
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Query a running API server for the 10 latest failed playbooks:

ara playbook list --client http \
  --server https://api.demo.recordsansible.org \
  --status failed \
  --limit 10

Get a list of playbooks matching a partial path and order the results by duration using the default offline API client:

ara playbook list --path="playbooks/site.yaml" --order=duration

Get a list of playbooks and format the results as json or yaml instead of pretty tables:

ara playbook list -f json
ara playbook list -f yaml

ara playbook show

$ ara playbook show --help
usage: ara playbook show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                         [--noindent] [--prefix PREFIX]
                         [--max-width <integer>] [--fit-width] [--print-empty]
                         [--client <client>] [--server <url>]
                         [--timeout <seconds>] [--username <username>]
                         [--password <password>] [--insecure]
                         <playbook-id>

Returns a detailed view of a specified playbook

positional arguments:
  <playbook-id>         Playbook to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Show details about a playbook from a running API server and format the result in json:

ara playbook show --client http --server https://api.demo.recordsansible.org 1 -f json

Show details about a playbook from a local installation using the default offline API client and format the result in yaml:

ara playbook show 1 -f yaml

ara playbook delete

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara playbook delete --help
usage: ara playbook delete [-h] [--client <client>] [--server <url>]
                           [--timeout <seconds>] [--username <username>]
                           [--password <password>] [--insecure]
                           <playbook-id>

Deletes the specified playbook and associated resources

positional arguments:
  <playbook-id>         Playbook to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

ara playbook prune

Pruning keeps the database size in check and the performance optimal by deleting older playbooks. It is recommended to run this command inside a task scheduler (such as cron) since the server does not run this command automatically.

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara playbook prune --help
usage: ara playbook prune [-h] [--client <client>] [--server <url>]
                          [--timeout <seconds>] [--username <username>]
                          [--password <password>] [--insecure] [--days DAYS]
                          [--label <label>] [--name <name>] [--path <path>]
                          [--status <status>] [--order <order>]
                          [--limit <limit>] [--confirm]

Deletes playbooks beyond a specified age in days

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --days DAYS           Delete playbooks started this many days ago (default:
                        31)
  --label <label>       Only delete playbooks matching the provided label
  --name <name>         Only delete playbooks matching the provided name (full
                        or partial)
  --path <path>         Only delete only playbooks matching the provided path
                        (full or partial)
  --status <status>     Only delete playbooks matching a specific status
                        ('completed', 'running', 'failed')
  --order <order>       Orders playbooks by a field ('id', 'created',
                        'updated', 'started', 'ended', 'duration')
                        Defaults to 'started' descending so the oldest
                        playbook would be deleted first.
                        The order can be reversed by using '-': ara playbook
                        list --order=-started
  --limit <limit>       Only delete the first <limit> determined by the
                        ordering. Defaults to ARA_CLI_LIMIT or 200.
  --confirm             Confirm deletion of playbooks, otherwise runs without
                        deleting any playbook

Examples:

# Return which playbooks would be deleted by ommitting --confirm
ara playbook prune

# Different retention for successful, unsuccessful and expired playbooks
ara playbook prune --status ok --days 30 --confirm
ara playbook prune --status failed --days 90 --confirm
ara playbook prune --status expired --days 3 --confirm

# Different retention based on labels
ara playbook prune --label dev --days 7 --confirm
ara playbook prune --label prod --days 90 --confirm

# Different retention based on name or path
ara playbook prune --name demo --days 7
ara playbook prune --path /home/jenkins --days 14

# Delete more than 200 playbooks per command execution
ara playbook prune --limit 9000 --confirm

ara play list

$ ara play list --help
usage: ara play list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                     [--quote {all,minimal,none,nonnumeric}] [--noindent]
                     [--max-width <integer>] [--fit-width] [--print-empty]
                     [--sort-column SORT_COLUMN] [--client <client>]
                     [--server <url>] [--timeout <seconds>]
                     [--username <username>] [--password <password>]
                     [--insecure] [--playbook <playbook_id>] [--name <name>]
                     [--uuid <uuid>] [--status <status>] [--long] [--resolve]
                     [--order <order>] [--limit <limit>]

Returns a list of plays based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --playbook <playbook_id>
                        List plays for the specified playbook
  --name <name>         List plays matching the provided name (full or
                        partial)
  --uuid <uuid>         List plays matching the provided uuid (full or
                        partial)
  --status <status>     List plays matching a specific status ('completed',
                        'running', 'failed')
  --long                Don't truncate paths
  --resolve             Resolve IDs to identifiers (such as path or names).
                        Defaults to ARA_CLI_RESOLVE or False
  --order <order>       Orders plays by a field ('id', 'created', 'updated',
                        'started', 'ended', 'duration')
                        Defaults to '-started' descending so the most recent
                        playbook is at the top.
                        The order can be reversed by omitting the '-': ara
                        play list --order=started
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Examples:

# List the top 25 longest plays
ara play list --order=-duration --limit 25

# List plays matching a name (full or partial)
ara play list --name apache

# List the plays for a specific playbook and format the result in json
ara play list --playbook 1 -f json

ara play show

$ ara play show --help
usage: ara play show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                     [--noindent] [--prefix PREFIX] [--max-width <integer>]
                     [--fit-width] [--print-empty] [--client <client>]
                     [--server <url>] [--timeout <seconds>]
                     [--username <username>] [--password <password>]
                     [--insecure]
                     <play-id>

Returns a detailed view of a specified play

positional arguments:
  <play-id>             Play to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Examples:

# Show a specific play and format the results as json
ara play show 9001 -f json

ara play delete

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara play delete --help
usage: ara play delete [-h] [--client <client>] [--server <url>]
                       [--timeout <seconds>] [--username <username>]
                       [--password <password>] [--insecure]
                       <play-id>

Deletes the specified play and associated resources

positional arguments:
  <play-id>             Play to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

ara host list

$ ara host list --help
usage: ara host list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                     [--quote {all,minimal,none,nonnumeric}] [--noindent]
                     [--max-width <integer>] [--fit-width] [--print-empty]
                     [--sort-column SORT_COLUMN] [--client <client>]
                     [--server <url>] [--timeout <seconds>]
                     [--username <username>] [--password <password>]
                     [--insecure] [--name <name>] [--playbook <playbook_id>]
                     [--with-changed | --without-changed]
                     [--with-failed | --without-failed]
                     [--with-unreachable | --without-unreachable] [--resolve]
                     [--long] [--order <order>] [--limit <limit>]

Returns a list of hosts based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --name <name>         List hosts matching the provided name (full or
                        partial)
  --playbook <playbook_id>
                        List hosts for a specified playbook id
  --with-changed        Return hosts with changed results
  --without-changed     Don't return hosts with changed results
  --with-failed         Return hosts with failed results
  --without-failed      Don't return hosts with failed results
  --with-unreachable    Return hosts with unreachable results
  --without-unreachable
                        Don't return hosts with unreachable results
  --resolve             Resolve IDs to identifiers (such as path or names).
                        Defaults to ARA_CLI_RESOLVE or False
  --long                Don't truncate paths
  --order <order>       Orders hosts by a field ('id', 'created', 'updated',
                        'name')
                        Defaults to '-updated' descending so the most recent
                        host is at the top.
                        The order can be reversed by omitting the '-': ara
                        host list --order=updated
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Note

From the perspective of ARA, each host is unique to a playbook run. Their records contain the Ansible host facts as well as their stats for a particular playbook run.

Examples:

# List the latest 25 host results
ara host list --limit 25

# List host records for a specific host name
ara host list --name localhost

# List all the host results for a specific playbook and format the result in json
ara host list --playbook 1 -f json

# Only return hosts with or without unreachable task results
ara host list --with-unreachable
ara host list --without-unreachable

# Only return hosts with or without changed task results
ara host list --with-changed
ara host list --without-changed

# Only return hosts with or without failed task results
ara host list --with-failed
ara host list --without-failed

ara host show

$ ara host show --help
usage: ara host show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                     [--noindent] [--prefix PREFIX] [--max-width <integer>]
                     [--fit-width] [--print-empty] [--client <client>]
                     [--server <url>] [--timeout <seconds>]
                     [--username <username>] [--password <password>]
                     [--insecure] [--with-facts]
                     <host-id>

Returns a detailed view of a specified host

positional arguments:
  <host-id>             Host to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --with-facts          Also include host facts in the response (use with '-f
                        json' or '-f yaml')

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Note

From the perspective of ARA, each host is unique to a playbook run. Their records contain the Ansible host facts as well as their stats for a particular playbook run.

Return stats for a specified host as well as a link to the playbook report it is involved in:

ara host show 1

Include host facts as well formatted in json:

# Facts do not render well in the default pretty table format
ara host show 1 --with-facts -f json

ara host delete

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara host delete --help
usage: ara host delete [-h] [--client <client>] [--server <url>]
                       [--timeout <seconds>] [--username <username>]
                       [--password <password>] [--insecure]
                       <host-id>

Deletes the specified host and associated resources

positional arguments:
  <host-id>             Host to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

ara record list

$ ara record list --help
usage: ara record list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                       [--quote {all,minimal,none,nonnumeric}] [--noindent]
                       [--max-width <integer>] [--fit-width] [--print-empty]
                       [--sort-column SORT_COLUMN] [--client <client>]
                       [--server <url>] [--timeout <seconds>]
                       [--username <username>] [--password <password>]
                       [--insecure] [--playbook <playbook_id>] [--key <key>]
                       [--long] [--resolve] [--order <order>]
                       [--limit <limit>]

Returns a list of records based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --playbook <playbook_id>
                        List records for the specified playbook
  --key <key>           List records matching the specified key
  --long                Don't truncate paths
  --resolve             Resolve IDs to identifiers (such as path or names).
                        Defaults to ARA_CLI_RESOLVE or False
  --order <order>       Orders records by a field ('id', 'created', 'updated',
                        'key')
                        Defaults to '-updated' descending so the most recent
                        record is at the top.
                        The order can be reversed by omitting the '-': ara
                        record list --order=updated
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Examples:

# List records for a specific key
ara record list --key log_url

# List records for a specific playbook
ara record list --playbook 9001

ara record show

$ ara record show --help
usage: ara record show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                       [--noindent] [--prefix PREFIX] [--max-width <integer>]
                       [--fit-width] [--print-empty] [--client <client>]
                       [--server <url>] [--timeout <seconds>]
                       [--username <username>] [--password <password>]
                       [--insecure]
                       <record-id>

Returns a detailed view of a specified record

positional arguments:
  <record-id>           Record to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Examples:

# Show a specific record and format the results as json
ara record show 9001 -f json

ara record delete

$ ara record delete --help
usage: ara record delete [-h] [--client <client>] [--server <url>]
                         [--timeout <seconds>] [--username <username>]
                         [--password <password>] [--insecure]
                         <record-id>

Deletes the specified record and associated resources

positional arguments:
  <record-id>           Record to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

ara result list

$ ara result list --help
usage: ara result list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                       [--quote {all,minimal,none,nonnumeric}] [--noindent]
                       [--max-width <integer>] [--fit-width] [--print-empty]
                       [--sort-column SORT_COLUMN] [--client <client>]
                       [--server <url>] [--timeout <seconds>]
                       [--username <username>] [--password <password>]
                       [--insecure] [--playbook <playbook_id>]
                       [--play <play_id>] [--task <task_id>]
                       [--host <host_id>] [--status <status>]
                       [--ignore-errors] [--changed] [--long] [--resolve]
                       [--order <order>] [--limit <limit>]

Returns a list of results based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --playbook <playbook_id>
                        List results for the specified playbook
  --play <play_id>      List results for the specified play
  --task <task_id>      List results for the specified task
  --host <host_id>      List results for the specified host
  --status <status>     List results matching a specific status:
                        ok, failed, skipped, unreachable, changed, ignored,
                        unknown
  --ignore-errors       Return only results with 'ignore_errors: true',
                        defaults to false
  --changed             Return only changed results, defaults to false
  --long                Don't truncate paths and include additional fields:
                        changed, ignore_errors, play
  --resolve             Resolve IDs to identifiers (such as path or names).
                        Defaults to ARA_CLI_RESOLVE or False
  --order <order>       Orders results by a field ('id', 'started', 'updated',
                        'ended', 'duration')
                        Defaults to '-started' descending so the most recent
                        result is at the top.
                        The order can be reversed by omitting the '-': ara
                        result list --order=started
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Return the 10 most recent failed results:

ara result list --status failed --limit 10

Return the 15 results with the highest duration for a specific playbook:

ara result list --playbook 389 --order=-duration --limit 15

ara result show

$ ara result show --help
usage: ara result show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                       [--noindent] [--prefix PREFIX] [--max-width <integer>]
                       [--fit-width] [--print-empty] [--client <client>]
                       [--server <url>] [--timeout <seconds>]
                       [--username <username>] [--password <password>]
                       [--insecure] [--with-content]
                       <result-id>

Returns a detailed view of a specified result

positional arguments:
  <result-id>           Result to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --with-content        Also include the result content in the response (use
                        with '-f json' or '-f yaml')

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Return detailed information about a specific result:

ara result show 9001

Return detailed information about a specific result, including formatted content:

ara result show 9001 --with-content -f json

ara result delete

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara result delete --help
usage: ara result delete [-h] [--client <client>] [--server <url>]
                         [--timeout <seconds>] [--username <username>]
                         [--password <password>] [--insecure]
                         <result-id>

Deletes the specified result and associated resources

positional arguments:
  <result-id>           Result to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

ara task list

$ ara task list --help
usage: ara task list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
                     [--quote {all,minimal,none,nonnumeric}] [--noindent]
                     [--max-width <integer>] [--fit-width] [--print-empty]
                     [--sort-column SORT_COLUMN] [--client <client>]
                     [--server <url>] [--timeout <seconds>]
                     [--username <username>] [--password <password>]
                     [--insecure] [--playbook <playbook_id>]
                     [--status <status>] [--name <name>] [--path <path>]
                     [--action <action>] [--long] [--resolve]
                     [--order <order>] [--limit <limit>]

Returns a list of tasks based on search queries

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False
  --playbook <playbook_id>
                        List tasks for a specified playbook id
  --status <status>     List tasks matching a specific status ('completed',
                        'running' or 'unknown')
  --name <name>         List tasks matching the provided name (full or
                        partial)
  --path <path>         List tasks matching the provided path (full or
                        partial)
  --action <action>     List tasks matching a specific action/ansible module
                        (ex: 'debug', 'package', 'set_fact')
  --long                Don't truncate paths and include additional fields:
                        path, lineno, handler, play
  --resolve             Resolve IDs to identifiers (such as path or names).
                        Defaults to ARA_CLI_RESOLVE or False
  --order <order>       Orders tasks by a field ('id', 'created', 'updated',
                        'started', 'ended', 'duration')
                        Defaults to '-started' descending so the most recent
                        task is at the top.
                        The order can be reversed by omitting the '-': ara
                        task list --order=started
  --limit <limit>       Returns the first <limit> determined by the ordering.
                        Defaults to ARA_CLI_LIMIT or 50.

output formatters:
  output formatter options

  -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns
  --sort-column SORT_COLUMN
                        specify the column(s) to sort the data (columns
                        specified first have a priority, non-existing columns
                        are ignored), can be repeated

CSV Formatter:
  --quote {all,minimal,none,nonnumeric}
                        when to include quotes, defaults to nonnumeric

json formatter:
  --noindent            whether to disable indenting the JSON

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Note

ara doesn’t have the concept of roles but it is possible to search for them by path, for example: ara task list --path "roles/install_apache"

Role names are included in the task names and it is possible to search for role-specific tasks there as well: ara task list --name install_apache.

Examples:

# Return the top 25 longest running tasks
ara task list --order=-duration --limit 25

# Return tasks from a specific playbook
ara task list --playbook 9001

# Return tasks for the package action
ara task list --action package

# Return tasks matching a path (partial or full)
ara task list --path="roles/install_apache"

# Return tasks matching a name (partial or full)
ara task list --name install_apache

ara task show

$ ara task show --help
usage: ara task show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
                     [--noindent] [--prefix PREFIX] [--max-width <integer>]
                     [--fit-width] [--print-empty] [--client <client>]
                     [--server <url>] [--timeout <seconds>]
                     [--username <username>] [--password <password>]
                     [--insecure]
                     <task-id>

Returns a detailed view of a specified task

positional arguments:
  <task-id>             Task to show

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

output formatters:
  output formatter options

  -f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
                        the output format, defaults to table
  -c COLUMN, --column COLUMN
                        specify the column(s) to include, can be repeated to
                        show multiple columns

json formatter:
  --noindent            whether to disable indenting the JSON

shell formatter:
  a format a UNIX shell can parse (variable="value")

  --prefix PREFIX       add a prefix to all variable names

table formatter:
  --max-width <integer>
                        Maximum display width, <1 to disable. You can also use
                        the CLIFF_MAX_TERM_WIDTH environment variable, but the
                        parameter takes precedence.
  --fit-width           Fit the table to the display width. Implied if --max-
                        width greater than 0. Set the environment variable
                        CLIFF_FIT_WIDTH=1 to always enable
  --print-empty         Print empty table if there is no data to show.

Return detailed information about a specific task:

ara task show 9001

ara task delete

Note

This command requires write privileges. You can read more about read and write permissions here.

$ ara task delete --help
usage: ara task delete [-h] [--client <client>] [--server <url>]
                       [--timeout <seconds>] [--username <username>]
                       [--password <password>] [--insecure]
                       <task-id>

Deletes the specified task and associated resources

positional arguments:
  <task-id>             Task to delete

optional arguments:
  -h, --help            show this help message and exit
  --client <client>     API client to use, defaults to ARA_API_CLIENT or
                        'offline'
  --server <url>        API server endpoint if using http client, defaults to
                        ARA_API_SERVER or 'http://127.0.0.1:8000'
  --timeout <seconds>   Timeout for requests to API server, defaults to
                        ARA_API_TIMEOUT or 30
  --username <username>
                        API server username for authentication, defaults to
                        ARA_API_USERNAME or None
  --password <password>
                        API server password for authentication, defaults to
                        ARA_API_PASSWORD or None
  --insecure            Ignore SSL certificate validation, defaults to
                        ARA_API_INSECURE or False

CLI: ara-manage (django API server)

ara-manage is a command provided by ARA when the API server dependencies are installed.

It is an alias to the python manage.py command interface provided by Django and they can be used interchangeably if you are running ARA from source.

Note

Django comes with a lot of built-in commands and they are not all used or relevant in the context of ARA so they might not be exposed, tested or documented.

This documentation provides information about commands which we think are relevant.

If you do not find a command documented here, you can find more information about it in the Django documentation.

Please feel free to send a patch if we’re missing anything !

ara-manage

$ ara-manage --help
[ara] No setting found for SECRET_KEY. Generating a random key...
[ara] Creating data & configuration directory: /home/docs/.ara/server
[ara] Writing default settings to /home/docs/.ara/server/settings.yaml
[ara] Using settings file: /home/docs/.ara/server/settings.yaml

Type 'ara-manage help <subcommand>' for help on a specific subcommand.

Available subcommands:

[api]
    prune

[auth]
    changepassword
    createsuperuser

[contenttypes]
    remove_stale_contenttypes

[django]
    check
    compilemessages
    createcachetable
    dbshell
    diffsettings
    dumpdata
    flush
    inspectdb
    loaddata
    makemessages
    makemigrations
    migrate
    sendtestemail
    shell
    showmigrations
    sqlflush
    sqlmigrate
    sqlsequencereset
    squashmigrations
    startapp
    startproject
    test
    testserver

[health_check]
    health_check

[rest_framework]
    generateschema

[sessions]
    clearsessions

[staticfiles]
    collectstatic
    findstatic
    runserver

[ui]
    generate

ara-manage prune

Warning

ara-manage prune has been replaced by ara playbook prune in ara 1.5. It will be removed in ara 1.6.

Used to delete playbooks that are older than a specified amount of days.

$ ara-manage prune --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage prune [-h] [--client CLIENT] [--endpoint ENDPOINT]
                        [--username USERNAME] [--password PASSWORD]
                        [--insecure] [--timeout TIMEOUT] [--days DAYS]
                        [--confirm] [--version] [-v {0,1,2,3}]
                        [--settings SETTINGS] [--pythonpath PYTHONPATH]
                        [--traceback] [--no-color] [--force-color]

Deletes playbooks from the database based on their age

optional arguments:
  -h, --help            show this help message and exit
  --client CLIENT       API client to use for the query: 'offline' or 'http'
                        (default: 'offline')
  --endpoint ENDPOINT   API endpoint to use for the query (default:
                        'http://127.0.0.1:8000')
  --username USERNAME   API username to use for the query (default: None)
  --password PASSWORD   API password to use for the query (default: None)
  --insecure            Disables SSL certificate validation
  --timeout TIMEOUT     Timeout for API queries (default: 10)
  --days DAYS           Delete playbooks started this many days ago (default:
                        31)
  --confirm             Confirm deletion of playbooks, otherwise runs without
                        deleting any playbook
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.

ara-manage changepassword

Change the password for a user.

Relevant when working with authentication.

$ ara-manage changepassword --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage changepassword [-h] [--database DATABASE] [--version]
                                 [-v {0,1,2,3}] [--settings SETTINGS]
                                 [--pythonpath PYTHONPATH] [--traceback]
                                 [--no-color] [--force-color]
                                 [username]

Change a user's password for django.contrib.auth.

positional arguments:
  username              Username to change password for; by default, it's the
                        current username.

optional arguments:
  -h, --help            show this help message and exit
  --database DATABASE   Specifies the database to use. Default is "default".
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.

ara-manage createsuperuser

Superusers are relevant when setting up authentication.

$ ara-manage createsuperuser --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage createsuperuser [-h] [--username USERNAME] [--noinput]
                                  [--database DATABASE] [--email EMAIL]
                                  [--version] [-v {0,1,2,3}]
                                  [--settings SETTINGS]
                                  [--pythonpath PYTHONPATH] [--traceback]
                                  [--no-color] [--force-color]

Used to create a superuser.

optional arguments:
  -h, --help            show this help message and exit
  --username USERNAME   Specifies the login for the superuser.
  --noinput, --no-input
                        Tells Django to NOT prompt the user for input of any
                        kind. You must use --username with --noinput, along
                        with an option for any other required field.
                        Superusers created with --noinput will not be able to
                        log in until they're given a valid password.
  --database DATABASE   Specifies the database to use. Default is "default".
  --email EMAIL         Specifies the email for the superuser.
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.

ara-manage makemigrations

Generally used to generate new SQL migrations after modifying the database model files.

$ ara-manage makemigrations --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage makemigrations [-h] [--dry-run] [--merge] [--empty]
                                 [--noinput] [-n NAME] [--no-header] [--check]
                                 [--version] [-v {0,1,2,3}]
                                 [--settings SETTINGS]
                                 [--pythonpath PYTHONPATH] [--traceback]
                                 [--no-color] [--force-color]
                                 [app_label [app_label ...]]

Creates new migration(s) for apps.

positional arguments:
  app_label             Specify the app label(s) to create migrations for.

optional arguments:
  -h, --help            show this help message and exit
  --dry-run             Just show what migrations would be made; don't
                        actually write them.
  --merge               Enable fixing of migration conflicts.
  --empty               Create an empty migration.
  --noinput, --no-input
                        Tells Django to NOT prompt the user for input of any
                        kind.
  -n NAME, --name NAME  Use this name for migration file(s).
  --no-header           Do not add header comments to new migration file(s).
  --check               Exit with a non-zero status if model changes are
                        missing migrations.
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.

ara-manage migrate

Runs SQL migrations.

They need to be run at least once before the API server can start.

$ ara-manage migrate --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage migrate [-h] [--noinput] [--database DATABASE] [--fake]
                          [--fake-initial] [--plan] [--run-syncdb] [--version]
                          [-v {0,1,2,3}] [--settings SETTINGS]
                          [--pythonpath PYTHONPATH] [--traceback] [--no-color]
                          [--force-color]
                          [app_label] [migration_name]

Updates database schema. Manages both apps with migrations and those without.

positional arguments:
  app_label             App label of an application to synchronize the state.
  migration_name        Database state will be brought to the state after that
                        migration. Use the name "zero" to unapply all
                        migrations.

optional arguments:
  -h, --help            show this help message and exit
  --noinput, --no-input
                        Tells Django to NOT prompt the user for input of any
                        kind.
  --database DATABASE   Nominates a database to synchronize. Defaults to the
                        "default" database.
  --fake                Mark migrations as run without actually running them.
  --fake-initial        Detect if tables already exist and fake-apply initial
                        migrations if so. Make sure that the current database
                        schema matches your initial migration before using
                        this flag. Django will only check for an existing
                        table name.
  --plan                Shows a list of the migration actions that will be
                        performed.
  --run-syncdb          Creates tables for apps without migrations.
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.

ara-manage runserver

Runs the embedded development server.

Note

Good for small scale usage.

Consider deploying with a WSGI application server and a web server for production use.

$ ara-manage runserver --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage runserver [-h] [--ipv6] [--nothreading] [--noreload]
                            [--nostatic] [--insecure] [--version]
                            [-v {0,1,2,3}] [--settings SETTINGS]
                            [--pythonpath PYTHONPATH] [--traceback]
                            [--no-color] [--force-color]
                            [addrport]

Starts a lightweight Web server for development and also serves static files.

positional arguments:
  addrport              Optional port number, or ipaddr:port

optional arguments:
  -h, --help            show this help message and exit
  --ipv6, -6            Tells Django to use an IPv6 address.
  --nothreading         Tells Django to NOT use threading.
  --noreload            Tells Django to NOT use the auto-reloader.
  --nostatic            Tells Django to NOT automatically serve static files
                        at STATIC_URL.
  --insecure            Allows serving static files even if DEBUG is False.
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.

ara-manage generate

Generates a static version of the built-in reporting web interface.

Note

Good for small scale usage but inefficient and contains a lot of small files at a large scale.

$ ara-manage generate --help
[ara] Using settings file: /home/docs/.ara/server/settings.yaml
usage: ara-manage generate [-h] [--version] [-v {0,1,2,3}]
                           [--settings SETTINGS] [--pythonpath PYTHONPATH]
                           [--traceback] [--no-color] [--force-color]
                           path

Generates a static tree of the web application

positional arguments:
  path                  Path where the static files will be built in

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -v {0,1,2,3}, --verbosity {0,1,2,3}
                        Verbosity level; 0=minimal output, 1=normal output,
                        2=verbose output, 3=very verbose output
  --settings SETTINGS   The Python path to a settings module, e.g.
                        "myproject.settings.main". If this isn't provided, the
                        DJANGO_SETTINGS_MODULE environment variable will be
                        used.
  --pythonpath PYTHONPATH
                        A directory to add to the Python path, e.g.
                        "/home/djangoprojects/myproject".
  --traceback           Raise on CommandError exceptions
  --no-color            Don't colorize the command output.
  --force-color         Force colorization of the command output.