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 metrics Provides metrics about hosts
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 metrics Provides metrics about playbooks
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 metrics Provides metrics about actions in tasks
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>] [--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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]
[--sort-ascending | --sort-descending]
[--client <client>] [--server <url>]
[--timeout <seconds>] [--username <username>]
[--password <password>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--insecure] [--label <label>]
[--ansible_version <ansible_version>]
[--client_version <client_version>]
[--server_version <server_version>]
[--python_version <python_version>] [--user <user>]
[--controller <controller>] [--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA or None
--insecure Ignore SSL certificate validation, defaults to
ARA_API_INSECURE or False
--label <label> List playbooks matching the provided label
--ansible_version <ansible_version>
List playbooks that ran with the specified Ansible
version (full or partial)
--client_version <client_version>
List playbooks that were recorded with the specified
ara client version (full or partial)
--server_version <server_version>
List playbooks that were recorded with the specified
ara server version (full or partial)
--python_version <python_version>
List playbooks that were recorded with the specified
python version (full or partial)
--user <user> List playbooks that were run by the specified user
(full or partial)
--controller <controller>
List playbooks that ran from the provided controller
(full or partial)
--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
--sort-ascending sort the column(s) in ascending order
--sort-descending sort the column(s) in descending order
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://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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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://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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>]
[--ssl-ca <path/to/cacert>] [--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA or None
--insecure Ignore SSL certificate validation, defaults to
ARA_API_INSECURE or False
ara playbook metrics¶
$ ara playbook metrics --help
usage: ara playbook metrics [-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]
[--sort-ascending | --sort-descending]
[--client <client>] [--server <url>]
[--timeout <seconds>] [--username <username>]
[--password <password>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>]
[--ssl-ca <path/to/cacert>] [--insecure]
[--aggregate {name,path,ansible_version,controller}]
[--label <label>]
[--ansible_version <ansible_version>]
[--client_version <client_version>]
[--server_version <server_version>]
[--python_version <python_version>]
[--name <name>] [--controller <controller>]
[--path <path>] [--status <status>] [--long]
[--order <order>] [--limit <limit>]
Provides metrics about playbooks
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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA or None
--insecure Ignore SSL certificate validation, defaults to
ARA_API_INSECURE or False
--aggregate {name,path,ansible_version,controller}
Aggregate playbooks by path, name, ansible version or
controller. Defaults to path.
--label <label> List playbooks matching the provided label
--ansible_version <ansible_version>
List playbooks that ran with the specified Ansible
version (full or partial)
--client_version <client_version>
List playbooks that were recorded with the specified
ara client version (full or partial)
--server_version <server_version>
List playbooks that were recorded with the specified
ara server version (full or partial)
--python_version <python_version>
List playbooks that were recorded with the specified
python version (full or partial)
--name <name> List playbooks matching the provided name (full or
partial)
--controller <controller>
List playbooks that ran from the provided controller
(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 1000.
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
--sort-ascending sort the column(s) in ascending order
--sort-descending sort the column(s) in descending order
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:
# Return metrics about more than the last 1000 playbooks
ara playbook metrics --limit 10000
# Return playbook metrics in json or csv
ara playbook metrics -f json
ara playbook metrics -f csv
# Return metrics about playbooks matching a (full or partial) path
ara playbook metrics --path site.yml
# Return metrics for playbooks matching a label
ara playbook metrics --label "check:False"
# Return additional metrics without truncating paths
ara playbook metrics --long
# Aggregate metrics by playbook path (default), name, by ansible version or by controller
ara playbook metrics --aggregate name
ara playbook metrics --aggregate ansible_version
ara playbook metrics --aggregate controller
ara playbook prune¶
Pruning keeps the database size in check and the performance optimal by deleting older playbooks.
Unused disk space can be reclaimed after pruning depending on your database backend, for example:
- sqlite:
sqlite3 ~/.ara/server/ansible.sqlite vacuum - mysql/mariadb:
mysqlcheck --optimize --databases ara - postgresql:
vacuumdb --dbname=ara
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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>]
[--ssl-ca <path/to/cacert>] [--insecure]
[--days DAYS] [--label <label>] [--name <name>]
[--user <user>]
[--ansible_version <ansible_version>]
[--client_version <client_version>]
[--server_version <server_version>]
[--python_version <python_version>]
[--controller <controller>] [--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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)
--user <user> Only delete playbooks that were executed by the
specified user (full or partial)
--ansible_version <ansible_version>
Only delete playbooks that ran with the specified
Ansible version (full or partial)
--client_version <client_version>
Only delete playbooks that were recorded with the
specified ara client version (full or partial)
--server_version <server_version>
Only delete playbooks that were recorded with the
specified ara server version (full or partial)
--python_version <python_version>
Only delete playbooks that were recorded with the
specified python version (full or partial)
--controller <controller>
Only delete playbooks that ran from the provided
controller (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 completed, failed and expired playbooks
ara playbook prune --status completed --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]
[--sort-ascending | --sort-descending]
[--client <client>] [--server <url>]
[--timeout <seconds>] [--username <username>]
[--password <password>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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
--sort-ascending sort the column(s) in ascending order
--sort-descending sort the column(s) in descending order
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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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]
[--sort-ascending | --sort-descending]
[--client <client>] [--server <url>]
[--timeout <seconds>] [--username <username>]
[--password <password>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--insecure] [--name <name>] [--playbook <playbook_id>]
[--latest] [--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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
--latest Return only the latest playbook report for each host
--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
--sort-ascending sort the column(s) in ascending order
--sort-descending sort the column(s) in descending order
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 last 25 host reports
ara host list --limit 25
# List only the latest playbook report for each host
ara host list --latest
# 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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA or None
--insecure Ignore SSL certificate validation, defaults to
ARA_API_INSECURE or False
ara host metrics¶
$ ara host metrics --help
usage: ara host metrics [-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]
[--sort-ascending | --sort-descending]
[--client <client>] [--server <url>]
[--timeout <seconds>] [--username <username>]
[--password <password>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--insecure] [--name <name>]
[--playbook <playbook_id>]
[--with-changed | --without-changed]
[--with-failed | --without-failed]
[--with-unreachable | --without-unreachable]
[--order <order>] [--limit <limit>]
Provides metrics about hosts
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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA or None
--insecure Ignore SSL certificate validation, defaults to
ARA_API_INSECURE or False
--name <name> Filter for hosts matching the provided name (full or
partial)
--playbook <playbook_id>
Filter for hosts for a specified playbook id
--with-changed Filter for hosts with changed results
--without-changed Filter out hosts without changed results
--with-failed Filter for hosts with failed results
--without-failed Filter out hosts without failed results
--with-unreachable Filter for hosts with unreachable results
--without-unreachable
Filter out hosts without unreachable results
--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
This influences the API request, not the ordering of
the metrics.
--limit <limit> Return metrics for the first <limit> determined by the
ordering. Defaults to ARA_CLI_LIMIT or 1000.
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
--sort-ascending sort the column(s) in ascending order
--sort-descending sort the column(s) in descending order
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:
# Return metrics about more than the last 1000 hosts
ara host metrics --limit 10000
# Return host metrics in json or csv
ara host metrics -f json
ara host metrics -f csv
# Return metrics for hosts matching a name
ara host metrics --name localhost
# Return metrics for hosts involved in a specific playbook
ara host metrics --playbook 9001
# Return metrics only for hosts with changed, failed or unreachable results
ara host metrics --with-changed
ara host metrics --with-failed
ara host metrics --with-unreachable
# Return metrics only for hosts without changed, failed or unreachable results
ara host metrics --without-changed
ara host metrics --without-failed
ara host metrics --without-unreachable
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]
[--sort-ascending | --sort-descending]
[--client <client>] [--server <url>]
[--timeout <seconds>] [--username <username>]
[--password <password>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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
--sort-ascending sort the column(s) in ascending order
--sort-descending sort the column(s) in descending order
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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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]
[--sort-ascending | --sort-descending]
[--client <client>] [--server <url>]
[--timeout <seconds>] [--username <username>]
[--password <password>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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
--sort-ascending sort the column(s) in ascending order
--sort-descending sort the column(s) in descending order
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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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]
[--sort-ascending | --sort-descending]
[--client <client>] [--server <url>]
[--timeout <seconds>] [--username <username>]
[--password <password>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--insecure] [--playbook <playbook_id>]
[--status <status>] [--name <name>] [--uuid <uuid>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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',
'expired', 'failed', 'running' or 'unknown')
--name <name> List tasks matching the provided name (full or
partial)
--uuid <uuid> List tasks matching the provided uuid (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
--sort-ascending sort the column(s) in ascending order
--sort-descending sort the column(s) in descending order
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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA 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>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA or None
--insecure Ignore SSL certificate validation, defaults to
ARA_API_INSECURE or False
ara task metrics¶
$ ara task metrics --help
usage: ara task metrics [-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]
[--sort-ascending | --sort-descending]
[--client <client>] [--server <url>]
[--timeout <seconds>] [--username <username>]
[--password <password>]
[--ssl-cert <path/to/certificate>]
[--ssl-key <path/to/key>] [--ssl-ca <path/to/cacert>]
[--insecure] [--aggregate {action,name,path}]
[--playbook <playbook_id>] [--status <status>]
[--name <name>] [--uuid <name>] [--path <path>]
[--action <action>] [--long] [--order <order>]
[--limit <limit>]
Provides metrics about actions in tasks
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
--ssl-cert <path/to/certificate>
If a client certificate is required, the path to the
certificate to use, defaults to ARA_API_CERT or None
--ssl-key <path/to/key>
If a client certificate is required, the path to the
private key to use, defaults to ARA_API_KEY or None
--ssl-ca <path/to/cacert>
Path to a certificate authority for trusting the API
server certificate, defaults to ARA_API_CA or None
--insecure Ignore SSL certificate validation, defaults to
ARA_API_INSECURE or False
--aggregate {action,name,path}
Aggregate tasks by action, name or path. Defaults to
action.
--playbook <playbook_id>
Filter for tasks for a specified playbook id
--status <status> Filter for tasks matching a specific status
('completed', 'expired', 'failed', 'running', or
'unknown')
--name <name> Filter for tasks matching the provided name (full or
partial)
--uuid <name> Filter for tasks matching the provided uuid (full or
partial)
--path <path> Filter for tasks matching the provided path (full or
partial)
--action <action> Filter for tasks matching a specific action/ansible
module (ex: 'debug', 'package', 'set_fact')
--long Don't truncate paths and include additional status
fields: completed, expired, failed, running & unknown
--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 metrics --order=started
This influences the API request, not the ordering of
the metrics.
--limit <limit> Return metrics for the first <limit> determined by the
ordering. Defaults to ARA_CLI_LIMIT or 1000.
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
--sort-ascending sort the column(s) in ascending order
--sort-descending sort the column(s) in descending order
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:
# Return metrics about more than the last 1000 tasks
ara task metrics --limit 10000
# Return task metrics in json or csv
ara task metrics -f json
ara task metrics -f csv
# Don't truncate paths and include additional task status fields
ara task metrics --long
# Return metrics about tasks from a specific playbook
ara task metrics --playbook 9001
# Return metrics for tasks matching a (full or partial) path
ara task metrics --path ansible-role-foo
# Only return metrics about a specific action
ara task metrics --action package
# Return metrics for tasks matching a name
ara task metrics --name apache
# Return metrics about the longest tasks and then sort them by total duration
ara task metrics --order=-duration --sort-column duration_total
# Aggregate metrics by task name rather than action
ara task metrics --aggregate name
# Aggregate metrics by task file rather than action
ara task metrics --aggregate path
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]
[--skip-checks]
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.
--skip-checks Skip system checks.
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] [--skip-checks]
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.
--skip-checks Skip system checks.
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] [--skip-checks]
[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.
--skip-checks Skip system checks.
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] [--check]
[--version] [-v {0,1,2,3}] [--settings SETTINGS]
[--pythonpath PYTHONPATH] [--traceback] [--no-color]
[--force-color] [--skip-checks]
[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.
--check Exits with a non-zero status if unapplied migrations
exist.
--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.
--skip-checks Skip system checks.
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]
[--skip-checks]
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.
--skip-checks Skip system checks.