# 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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 10)

Command ['ara', '--help'] failed: [Errno 2] No such file or directory: 'ara'

## ara expire

Note

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 20)

Command ['ara', 'expire', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 35)

Command ['ara', 'playbook', 'list', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 63)

Command ['ara', 'playbook', 'show', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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.

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 86)

Command ['ara', 'playbook', 'delete', '--help'] failed: [Errno 2] No such file or directory: 'ara'

## ara playbook metrics

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 91)

Command ['ara', 'playbook', 'metrics', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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.

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 137)

Command ['ara', 'playbook', 'prune', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 165)

Command ['ara', 'play', 'list', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 183)

Command ['ara', 'play', 'show', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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.

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 200)

Command ['ara', 'play', 'delete', '--help'] failed: [Errno 2] No such file or directory: 'ara'

## ara host list

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 205)

Command ['ara', 'host', 'list', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 244)

Command ['ara', 'host', 'show', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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.

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 274)

Command ['ara', 'host', 'delete', '--help'] failed: [Errno 2] No such file or directory: 'ara'

## ara host metrics

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 279)

Command ['ara', 'host', 'metrics', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 311)

Command ['ara', 'record', 'list', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 326)

Command ['ara', 'record', 'show', '--help'] failed: [Errno 2] No such file or directory: 'ara'

Examples:

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

## ara record delete

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 338)

Command ['ara', 'record', 'delete', '--help'] failed: [Errno 2] No such file or directory: 'ara'

## ara result list

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 343)

Command ['ara', 'result', 'list', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 360)

Command ['ara', 'result', 'show', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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.

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 382)

Command ['ara', 'result', 'delete', '--help'] failed: [Errno 2] No such file or directory: 'ara'

## ara task list

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 387)

Command ['ara', 'task', 'list', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 419)

Command ['ara', 'task', 'show', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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.

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 435)

Command ['ara', 'task', 'delete', '--help'] failed: [Errno 2] No such file or directory: 'ara'

## ara task metrics

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 440)

Command ['ara', 'task', 'metrics', '--help'] failed: [Errno 2] No such file or directory: 'ara'

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 501)

Command ['ara-manage', '--help'] failed: [Errno 2] No such file or directory: 'ara-manage'

## 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.

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 512)

Command ['ara-manage', 'prune', '--help'] failed: [Errno 2] No such file or directory: 'ara-manage'

## ara-manage changepassword

Change the password for a user.

Relevant when working with authentication.

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 521)

Command ['ara-manage', 'changepassword', '--help'] failed: [Errno 2] No such file or directory: 'ara-manage'

## ara-manage createsuperuser

Superusers are relevant when setting up authentication.

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 528)

Command ['ara-manage', 'createsuperuser', '--help'] failed: [Errno 2] No such file or directory: 'ara-manage'

## ara-manage makemigrations

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 535)

Command ['ara-manage', 'makemigrations', '--help'] failed: [Errno 2] No such file or directory: 'ara-manage'

## ara-manage migrate

Runs SQL migrations.

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

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 544)

Command ['ara-manage', 'migrate', '--help'] failed: [Errno 2] No such file or directory: 'ara-manage'

## 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.

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 556)

Command ['ara-manage', 'runserver', '--help'] failed: [Errno 2] No such file or directory: 'ara-manage'

## 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.

System Message: ERROR/6 (/build/python-ara-kIIrV2/python-ara-1.5.8/doc/source/cli.rst, line 566)

Command ['ara-manage', 'generate', '--help'] failed: [Errno 2] No such file or directory: 'ara-manage'