Metadata-Version: 2.4
Name: ascender-kit
Version: 25.5.1
Summary: The official command line interface for Ascender Automation
Home-page: https://github.com/ctrliq/ascender-kit
Author: Ascender Project Contributors
Author-email: info@ctrliq.com
License: Apache 2.0
Project-URL: Homepage, https://ascender-automation.org
Project-URL: Source, https://github.com/ctrliq/ascender-kit
Project-URL: Issues, https://github.com/ctrliq/ascender-kit/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.txt
Requires-Dist: packaging
Requires-Dist: PyYAML
Requires-Dist: requests
Requires-Dist: urllib3
Provides-Extra: formatting
Requires-Dist: jq; extra == "formatting"
Provides-Extra: websockets
Requires-Dist: websocket-client>=1.0.0; extra == "websockets"
Provides-Extra: crypto
Requires-Dist: cryptography; extra == "crypto"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Ascender Kit

Ascender Kit provides `ascender`, the official command line client for [Ascender](https://github.com/ctrliq/ascender), along with the Python library that backs it.

Rather than hard-coding a list of commands, the CLI discovers what your server supports at runtime by issuing HTTP OPTIONS requests against the Ascender REST API. The set of resources, actions, and arguments you see is therefore the set your particular Ascender version actually offers.

Features
--------

- **Runtime API discovery** — resources and their arguments come from the server, not a hard-coded table
- **Consistent output formats** — JSON by default, with YAML and human-readable tables via `-f`
- **Field filtering** — narrow output to the columns you care about with `--filter`
- **Token-based authentication** — generate and store OAuth2.0 tokens with `ascender login`
- **Job monitoring** — follow job output as it streams over a websocket with `--monitor`
- **Import and export** — move resources between servers with `ascender export` and `ascender import`
- **Python library** — the same API client is importable as `ascenderkit` for use in your own tooling

Installation
------------

    pip install ascender-kit

Some capabilities are kept behind optional extras so the base install stays small:

    pip install ascender-kit[websockets]   # job output streaming
    pip install ascender-kit[formatting]   # jq-style filtering of JSON output
    pip install ascender-kit[crypto]       # encrypted credential support

Ascender Kit requires Python 3.11 or newer.

Getting Started
---------------

Point the client at your server and confirm it can authenticate:

    export CONTROLLER_HOST=https://ascender.example.org
    export CONTROLLER_USERNAME=alice
    export CONTROLLER_PASSWORD=secret

    ascender config

Because the command set is discovered from the server, `--help` is the reference:

    ascender --help                      # every available resource
    ascender job_templates --help        # every action on job templates
    ascender job_templates launch --help # every argument for one action

A few common operations:

    ascender jobs list -f human --filter name,created,status
    ascender job_templates launch 'Example Job Template' --monitor -f human
    ascender export > resources.json

For repeated use, generate a token instead of passing credentials each time:

    $(ascender login -f human)

Documentation
-------------

- Full CLI documentation lives in [`ascenderkit/cli/docs`](https://github.com/ctrliq/ascender-kit/tree/main/ascenderkit/cli/docs) and covers usage, authentication, output formats, and worked examples.
- Ascender documentation is available at [Ascender Documentation](https://docs.ascender-automation.org).

Contributing
------------

- See [CONTRIBUTING.md](https://github.com/ctrliq/ascender-kit/blob/main/CONTRIBUTING.md) for development setup, testing, and pull request guidelines.
- Join us on our [forum](https://forum.ascender-automation.org) to discuss development topics.

Reporting Issues
----------------

- If you're experiencing a problem that you feel is a bug in Ascender Kit, or have ideas for improving it, we encourage you to open a GitHub issue and share your feedback.
- For security vulnerabilities, please follow the process in [SECURITY.md](https://github.com/ctrliq/ascender-kit/blob/main/SECURITY.md) rather than opening a public issue.

License
-------

Apache License 2.0. See [LICENSE](https://github.com/ctrliq/ascender-kit/blob/main/LICENSE) and [NOTICE.txt](https://github.com/ctrliq/ascender-kit/blob/main/NOTICE.txt).
