# Steampunk Spotter Command-Line Interface (CLI)
[](https://pypi.org/project/steampunk-spotter/)
[Steampunk Spotter] is an Ansible Playbook Platform that scans, analyzes,
enhances, and provides insights for your playbooks.
The Steampunk Spotter CLI enables the use from the console with the ability
to scan Ansible content such as playbooks, roles, collections, or task files.
The following instructions explain how to get started with the Steampunk
Spotter CLI to scan Ansible content and get recommendations.
## Installation
Steampunk Spotter CLI requires Python 3 and is available as a
[steampunk-spotter] Python package.
```shell
$ pip install steampunk-spotter
```
We recommend installing the package into a clean Python virtual environment.
## Usage
After the CLI is installed, you can explore its commands and options by
running `spotter --help`.
The `--help/-h` option is also available for every command.
### Limitations
The current release version of Steampunk Spotter contains the following
limitations that also apply to the CLI:
- with the FREE subscription plan, you can perform up to 100 scans/month,
- with the INDIVIDUAL, TEAM, or ENTERPRISE subscription plan you can perform
an unlimited number of scans,
- for the ENTERPRISE subscription plan, contact us at steampunk@xlab.si to
discuss your needs.
### Authentication
To use CLI, you have to supply your Steampunk Spotter user account credentials.
If you don't have an account, use `spotter register` command that will direct
you to the page where you can create one.
Steampunk Spotter supports two kinds of credentials: 1) API token (can be
generated in the user settings within the Spotter App), and 2) username and
password.
- Use `--token/-t` global option to supply your token credential.
Alternatively, set the `SPOTTER_TOKEN` environment variable to contain
the API token.
- Use `--username/-u` and `--password/-p` global options to supply your
username and password. Alternatively, set the `SPOTTER_USERNAME` and
`SPOTTER_PASSWORD` environment variables.
- You can run `spotter <options> login` to persist your credentials in the
Steampunk Spotter CLI's local storage, where `<options>` stand for one
of the approaches described above.
After that, you can start scanning right away.
### Scanning
The CLI `spotter scan` command is used for scanning Ansible
content (playbooks, roles, collections, or task files) and returning the
scan results.
#### Ansible content
The `scan` command will automatically detect the type of your Ansible content
and scan it.
Here are some examples of running scans:
```shell
# scan playbook
$ spotter scan path/to/playbook.yaml
# scan multiple files at once
$ spotter scan path/to/taskfile.yaml \
path/to/playbook.yaml \
path/to/role \
path/to/collection
# scan any folder that contains Ansible content
$ spotter scan path/to/folder
```
#### Selecting the target project
*This part is only relevant for users with a TEAM plan or higher.*
By default, the scan results are stored in the first project of the user's
first organization (in the app).
Users that have multiple organizations or projects in the app can use
`--project-id` option to specify the UUID of an existing target project, where
the scan result will be stored.
```shell
$ spotter scan --project-id <project-id> .
```
You can learn your project id by logging into the app, selecting the
appropriate organization and navigating to the project's dashboard.
#### Excluding values
By default, CLI parses full Ansible YAML content with all values from
playbooks (e.g., parameter values from Ansible modules,
variables from Ansible plays, etc.).
With values, we can discover additional tips for improvements.
CLI will try to detect and omit any secrets (e.g., passwords, SSH keys,
cloud credentials, etc.) from being transmitted.
If you want to omit parsing and sending the values, you can use
`--exclude-values` option.
```shell
$ spotter scan --exclude-values playbook.yaml
```
#### Excluding metadata
By default, CLI collects metadata (i.e., file names, line, and column numbers,
YAML markers) from Ansible content.
This is needed for enriched user experience in the Spotter App and to get
additional tips for improvements.
If you want to use metadata just for displaying the scan output, which means
that no data about your Ansible content structure is sent to the backend
server, you can use `--exclude-metadata` option.
```shell
$ spotter scan --exclude-metadata playbook.yaml
```
#### Automated application of suggestions to your code
There is also a `--rewrite` option that rewrites your files with fixes after
scanning.
This action will modify your files.
```shell
$ spotter scan --rewrite playbook.yaml
```
### Next steps
For more comprehensive usage, issue `spotter scan --help`.
Please refer to [Steampunk Spotter Documentation] for further instructions.
## Acknowledgment
This tool was created by [XLAB Steampunk], IT automation specialists and
leading experts in building Enterprise Ansible Collections.
[Steampunk Spotter]: https://spotter.steampunk.si/
[steampunk-spotter]: https://pypi.org/project/steampunk-spotter/
[Steampunk Spotter Documentation]: https://spotter.steampunk.si/docs/
[XLAB Steampunk]: https://steampunk.si/
Raw data
{
"_id": null,
"home_page": "https://spotter.steampunk.si/",
"name": "steampunk-spotter",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "ansible, automation, spotter, scanner, quality, playbook, steampunk",
"author": "XLAB d.o.o.",
"author_email": "\"XLAB d.o.o.\" <pypi@xlab.si>",
"download_url": null,
"platform": null,
"description": "# Steampunk Spotter Command-Line Interface (CLI)\n\n[](https://pypi.org/project/steampunk-spotter/)\n\n[Steampunk Spotter] is an Ansible Playbook Platform that scans, analyzes,\nenhances, and provides insights for your playbooks.\n\nThe Steampunk Spotter CLI enables the use from the console with the ability\nto scan Ansible content such as playbooks, roles, collections, or task files.\n\nThe following instructions explain how to get started with the Steampunk\nSpotter CLI to scan Ansible content and get recommendations.\n\n## Installation\nSteampunk Spotter CLI requires Python 3 and is available as a\n[steampunk-spotter] Python package.\n\n```shell\n$ pip install steampunk-spotter\n```\n\nWe recommend installing the package into a clean Python virtual environment.\n\n## Usage\nAfter the CLI is installed, you can explore its commands and options by\nrunning `spotter --help`.\nThe `--help/-h` option is also available for every command.\n\n### Limitations\nThe current release version of Steampunk Spotter contains the following\nlimitations that also apply to the CLI: \n\n- with the FREE subscription plan, you can perform up to 100 scans/month,\n- with the INDIVIDUAL, TEAM, or ENTERPRISE subscription plan you can perform \n an unlimited number of scans,\n- for the ENTERPRISE subscription plan, contact us at steampunk@xlab.si to\n discuss your needs.\n\n### Authentication\nTo use CLI, you have to supply your Steampunk Spotter user account credentials.\nIf you don't have an account, use `spotter register` command that will direct\nyou to the page where you can create one.\n\nSteampunk Spotter supports two kinds of credentials: 1) API token (can be\ngenerated in the user settings within the Spotter App), and 2) username and\npassword.\n\n- Use `--token/-t` global option to supply your token credential.\n Alternatively, set the `SPOTTER_TOKEN` environment variable to contain \n the API token.\n- Use `--username/-u` and `--password/-p` global options to supply your\n username and password. Alternatively, set the `SPOTTER_USERNAME` and\n `SPOTTER_PASSWORD` environment variables.\n- You can run `spotter <options> login` to persist your credentials in the\n Steampunk Spotter CLI's local storage, where `<options>` stand for one\n of the approaches described above.\n\nAfter that, you can start scanning right away.\n\n### Scanning\nThe CLI `spotter scan` command is used for scanning Ansible\ncontent (playbooks, roles, collections, or task files) and returning the\nscan results.\n\n#### Ansible content\nThe `scan` command will automatically detect the type of your Ansible content\nand scan it.\nHere are some examples of running scans:\n\n```shell\n# scan playbook\n$ spotter scan path/to/playbook.yaml\n\n# scan multiple files at once\n$ spotter scan path/to/taskfile.yaml \\\n path/to/playbook.yaml \\\n path/to/role \\\n path/to/collection\n\n# scan any folder that contains Ansible content\n$ spotter scan path/to/folder\n```\n\n#### Selecting the target project\n*This part is only relevant for users with a TEAM plan or higher.*\n\nBy default, the scan results are stored in the first project of the user's\nfirst organization (in the app).\n\nUsers that have multiple organizations or projects in the app can use\n`--project-id` option to specify the UUID of an existing target project, where\nthe scan result will be stored.\n\n```shell\n$ spotter scan --project-id <project-id> .\n```\n\nYou can learn your project id by logging into the app, selecting the\nappropriate organization and navigating to the project's dashboard.\n\n#### Excluding values\nBy default, CLI parses full Ansible YAML content with all values from\nplaybooks (e.g., parameter values from Ansible modules,\nvariables from Ansible plays, etc.).\nWith values, we can discover additional tips for improvements.\nCLI will try to detect and omit any secrets (e.g., passwords, SSH keys, \ncloud credentials, etc.) from being transmitted.\nIf you want to omit parsing and sending the values, you can use\n`--exclude-values` option.\n\n```shell\n$ spotter scan --exclude-values playbook.yaml\n```\n\n#### Excluding metadata\nBy default, CLI collects metadata (i.e., file names, line, and column numbers,\nYAML markers) from Ansible content.\nThis is needed for enriched user experience in the Spotter App and to get\nadditional tips for improvements.\nIf you want to use metadata just for displaying the scan output, which means\nthat no data about your Ansible content structure is sent to the backend\nserver, you can use `--exclude-metadata` option.\n\n```shell\n$ spotter scan --exclude-metadata playbook.yaml\n```\n\n#### Automated application of suggestions to your code\nThere is also a `--rewrite` option that rewrites your files with fixes after\nscanning.\nThis action will modify your files.\n\n```shell\n$ spotter scan --rewrite playbook.yaml\n```\n\n### Next steps\nFor more comprehensive usage, issue `spotter scan --help`.\nPlease refer to [Steampunk Spotter Documentation] for further instructions.\n\n## Acknowledgment\nThis tool was created by [XLAB Steampunk], IT automation specialists and\nleading experts in building Enterprise Ansible Collections.\n\n[Steampunk Spotter]: https://spotter.steampunk.si/\n[steampunk-spotter]: https://pypi.org/project/steampunk-spotter/\n[Steampunk Spotter Documentation]: https://spotter.steampunk.si/docs/\n[XLAB Steampunk]: https://steampunk.si/\n",
"bugtrack_url": null,
"license": null,
"summary": "Ansible Playbook Platform that scans, analyzes, enhances, and provides insights for your playbooks.",
"version": "5.0.0",
"project_urls": {
"Bug Tracker": "https://gitlab.com/xlab-steampunk/steampunk-spotter-client/spotter-cli/-/issues",
"Changelog": "https://gitlab.com/xlab-steampunk/steampunk-spotter-client/spotter-cli/-/blob/main/CHANGELOG.txt",
"Documentation": "https://spotter.steampunk.si/docs/",
"Homepage": "https://spotter.steampunk.si/",
"Source Code": "https://gitlab.com/xlab-steampunk/steampunk-spotter-client/spotter-cli"
},
"split_keywords": [
"ansible",
" automation",
" spotter",
" scanner",
" quality",
" playbook",
" steampunk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7bc93b1ef605b54a6df8f5a5474166827f4f89aa8e033f672e083ca5ec5e72f7",
"md5": "f9854abd49002e477b3a7a8c9105bc88",
"sha256": "276e4286967face8fd153b77a50fb05a2f0bfd111467d1f94ce8437768964b09"
},
"downloads": -1,
"filename": "steampunk_spotter-5.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f9854abd49002e477b3a7a8c9105bc88",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 113048,
"upload_time": "2024-10-28T12:41:28",
"upload_time_iso_8601": "2024-10-28T12:41:28.218856Z",
"url": "https://files.pythonhosted.org/packages/7b/c9/3b1ef605b54a6df8f5a5474166827f4f89aa8e033f672e083ca5ec5e72f7/steampunk_spotter-5.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-28 12:41:28",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "xlab-steampunk",
"gitlab_project": "steampunk-spotter-client",
"lcname": "steampunk-spotter"
}
JSON