hctl 0.1.0__tar.gz

hctl-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+Harness CLI should be a useful, welcoming place for people building and using
+developer tools.
+
+## Standards
+
+Please:
+
+- Be respectful, patient, and direct.
+- Assume good intent, especially when discussing bugs or unclear behavior.
+- Share context, reproduction steps, and evidence when reporting problems.
+- Keep feedback focused on the work and its impact.
+- Respect privacy. Do not post API keys, private account identifiers, customer
+  data, or private endpoint payloads.
+
+Please do not:
+
+- Harass, threaten, insult, or demean other contributors.
+- Use sexualized, discriminatory, or exclusionary language.
+- Publish another person's private information.
+- Derail technical discussions with repeated off-topic comments.
+- Pressure maintainers or contributors for unpaid work on your timeline.
+
+## Enforcement
+
+Maintainers may edit, hide, or remove content that violates this code of
+conduct. They may also warn contributors, temporarily limit participation, or
+block participation when behavior creates risk for other people or the project.
+
+If you see a problem, contact the repository owner privately with the relevant
+links, screenshots, or command output. Reports will be handled with care and
+with as much confidentiality as practical.

hctl-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+Thanks for helping make the Harness CLI better.
+
+Please read and follow the [Code of Conduct](CODE_OF_CONDUCT.md). Keep issues
+and pull requests focused on making the CLI clearer, safer, and more useful.
+
+## Local Setup
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+uv run python -m unittest
+```
+
+The CLI has no runtime dependencies. Keep new dependencies out unless they
+remove meaningful complexity and are worth the installation cost.
+
+Install local formatting hooks when you start contributing:
+
+```bash
+uv run --extra dev pre-commit install
+uv run --extra dev pre-commit run --all-files
+```
+
+The hooks run Ruff through `uv` so formatting and autofixable lint issues are
+caught before CI gets to make a dramatic little entrance.
+
+## Endpoint Manifest
+
+Endpoint commands are generated from the official Harness API docs:
+
+```bash
+uv run python scripts/update_openapi_manifest.py
+```
+
+Commit generated changes together with the generator or runtime code that needs
+them. If the upstream docs change in a way that removes endpoints, call that out
+in the pull request.
+
+## Releases
+
+The public package and command name is `hctl`. See
+[docs/distribution.md](docs/distribution.md) for the supported install
+channels, release checklist, PyPI trusted-publishing setup, Homebrew formula
+handoff, standalone zipapp artifact, and curl installer behavior.
+
+## Pull Requests
+
+Use the pull request template and include the command output that proves the
+changed CLI behavior. For request-building changes, `hctl ... --dry-run`
+output is usually the most useful evidence.
+
+Before opening a PR:
+
+```bash
+uv run ruff format .
+uv run python -m unittest
+uv run python scripts/validate_openapi_manifest.py
+uv run python -m compileall -q src tests scripts
+uv run ruff check .
+uv run mypy src/harness_cli
+uv build --sdist --wheel
+```
+
+GitHub Actions runs the same checks through `uv sync --locked --all-extras --dev`
+on Python 3.10 through 3.13, including `ruff format --check .`, package build,
+and an installed-wheel smoke test.
+
+Please keep changes focused. Small, well-documented slices are much easier to
+review than a giant mystery crate of enthusiasm.

hctl-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ian Matson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

hctl-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include LICENSE
+include README.md
+include SECURITY.md
+include install.sh
+include pyproject.toml
+recursive-include docs *.md
+recursive-include scripts *.py
+recursive-include tests *.py

hctl-0.1.0/PKG-INFO

@@ -0,0 +1,349 @@
+Metadata-Version: 2.4
+Name: hctl
+Version: 0.1.0
+Summary: Polished OpenAPI-backed command line interface for Harness APIs.
+Author: Ian Matson
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/imatson9119/harness-cli
+Project-URL: Repository, https://github.com/imatson9119/harness-cli
+Project-URL: Issues, https://github.com/imatson9119/harness-cli/issues
+Keywords: harness,cli,openapi,devops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# hctl
+
+`hctl` is a polished, OpenAPI-backed command line interface for the Harness
+Software Delivery Platform APIs.
+
+The CLI is generated from the public Harness API reference at
+<https://apidocs.harness.io/>. The current manifest includes every operation
+published in the Redocly OpenAPI shared data bundle that is practical to expose
+through a generic CLI caller.
+
+## Install
+
+Install the latest code from Git with `uv`:
+
+```bash
+uv tool install git+https://github.com/imatson9119/harness-cli.git
+hctl --help
+```
+
+After the first PyPI release, the shortest install path is:
+
+```bash
+uv tool install hctl
+```
+
+The curl installer prefers the latest GitHub Release artifact and falls back to
+the Git install path when no release artifact is available:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/imatson9119/harness-cli/main/install.sh | sh
+```
+
+Other supported channels:
+
+```bash
+pipx install hctl
+brew tap imatson9119/tap && brew install hctl
+curl -fsSLO https://github.com/imatson9119/harness-cli/releases/latest/download/hctl.pyz
+chmod +x hctl.pyz
+./hctl.pyz --help
+```
+
+See [docs/distribution.md](docs/distribution.md) for upgrade, uninstall,
+release, Homebrew, PyPI, and standalone artifact details.
+
+Upgrade and remove common installs:
+
+```bash
+uv tool upgrade hctl
+uv tool uninstall hctl
+brew upgrade hctl
+brew uninstall hctl
+rm ~/.local/bin/hctl
+```
+
+## Onboarding
+
+Run the interactive onboarding flow:
+
+```bash
+hctl init
+```
+
+The flow stores configuration in `~/.config/hctl/config.json` by default and
+sets file permissions to `0600`. Config is profile-based, so you can keep
+multiple Harness accounts or projects handy:
+
+```bash
+hctl init --profile prod --output table
+hctl init --profile sandbox
+hctl profile use prod
+hctl profile list
+```
+
+Onboarding asks for host, API key, account, org, project, and default output
+mode. Host values must be full `http://` or `https://` URLs. Use
+`--non-interactive` with flags when scripting setup.
+
+Use global options when you want one command to use a different profile or
+config file without changing your active setup:
+
+```bash
+hctl --profile prod doctor
+hctl --config ./harness.config.json auth status
+```
+
+You can also use environment variables:
+
+```bash
+export HARNESS_HOST=https://app.harness.io
+export HARNESS_API_KEY=your-token
+export HARNESS_PROFILE=prod
+export HARNESS_ACCOUNT=your-account-id
+export HARNESS_ORG=optional-org-id
+export HARNESS_PROJECT=optional-project-id
+```
+
+Harness authenticates API calls with the `x-api-key` header. When an endpoint
+requires the Harness account header, `--account` or the active profile account
+is sent as `Harness-Account`. Profile account, org, and project values are also
+used for common generated endpoint parameter spellings such as
+`accountIdentifier`, `accountId`, `account_id`, `orgIdentifier`,
+`organizationIdentifier`, `projectIdentifier`, and snake-case registry
+identifiers.
+
+## Endpoint Commands
+
+List generated operations:
+
+```bash
+hctl api list --search pipeline
+hctl api list --search role --wide
+hctl api groups --search pipeline --limit 20
+hctl api list --tag "Account Roles"
+hctl api list --group account-roles --has-body
+hctl api list --method post --path /v1/roles
+```
+
+Describe an operation:
+
+```bash
+hctl api describe list-roles-acc
+```
+
+Descriptions include parameter defaults, enum hints, docs links, pagination
+support, and pasteable examples.
+
+Print a request-body template for create/update operations:
+
+```bash
+hctl api body create-role-acc > role.json
+hctl api body create-account-scoped-connector --content-type application/yaml > connector.yaml
+hctl api body create-role-acc --output-file role.json
+hctl api body create-role-acc --json
+```
+
+JSON templates are pretty-printed as JSON. YAML and other text templates are
+printed as editable raw text; add `--json` when you want metadata such as the
+selected content type wrapped around the body.
+
+Call an operation through the stable API dispatcher:
+
+```bash
+hctl api call --help
+hctl api call list-roles-acc --help
+hctl api call list-roles-acc --query limit=10 --help
+hctl api call list-roles-acc --query limit=10
+```
+
+Call the same operation through its generated group shortcut:
+
+```bash
+hctl account-roles list-roles-acc --limit 10
+```
+
+Use `--host https://custom.example.com` for one-off calls against another
+Harness base URL. Like saved hosts, per-call host overrides must be full
+`http://` or `https://` URLs without query strings or fragments.
+
+Render JSON list responses as a table when you want a compact human view:
+
+```bash
+hctl account-roles list-roles-acc --limit 10 --output table
+hctl account-roles list-roles-acc --limit 10 --output table --columns identifier,name,createdAt
+```
+
+Fetch paginated list endpoints until they are exhausted:
+
+```bash
+hctl account-roles list-roles-acc --all --all-page-size 100 --output table
+```
+
+`--all` recognizes the common pagination shapes in the generated Harness
+manifest, including page, offset, and cursor-style query parameters.
+
+Preview the request without sending it:
+
+```bash
+hctl account-roles list-roles-acc --limit 10 --dry-run
+hctl account-roles list-roles-acc --limit 10 --curl
+```
+
+Preview output redacts `x-api-key`, `Authorization`, and common token/secret
+style headers so requests are easier to share safely.
+
+Send JSON request bodies from a file:
+
+```bash
+hctl project-services create-service --org my-org --project my-project --body @service.json
+hctl project-services create-service --org my-org --project my-project --body-json @service.json
+hctl api call create-role-acc --body-template --dry-run
+```
+
+Use `--body-json` for inline JSON, `@file`, or `-` stdin when you want the CLI
+to validate the payload before sending it. Use `--body-template` to send the
+generated JSON or YAML request-body sample for an operation; pair it with
+`--dry-run` first when exploring a new endpoint.
+
+Upload multipart files for file-oriented endpoints:
+
+```bash
+hctl artifact-signing upload-signature \
+  --org my-org \
+  --project my-project \
+  --form note=release \
+  --file signature=@signature.json
+```
+
+Save binary responses:
+
+```bash
+hctl file-store download-file --identifier readme --output-file readme.md
+```
+
+## Shell Completion
+
+Print completion scripts for supported shells:
+
+```bash
+hctl completion bash
+hctl completion zsh
+hctl completion fish
+```
+
+Install completions:
+
+```bash
+mkdir -p ~/.local/share/bash-completion/completions
+hctl completion bash > ~/.local/share/bash-completion/completions/hctl
+mkdir -p ~/.zfunc
+hctl completion zsh > ~/.zfunc/_hctl
+mkdir -p ~/.config/fish/completions
+hctl completion fish > ~/.config/fish/completions/hctl.fish
+```
+
+## Terminal Experience
+
+Interactive terminals get colorized tables, highlighted JSON, Unicode table
+frames, and a live status indicator while API calls are in flight. Scripts
+still get clean output: command data goes to stdout, while status, saved-file
+messages, and clean transport errors go to stderr. HTTP 4xx/5xx responses
+return exit code `1` and still render the response body so scripts can inspect
+it.
+
+Controls:
+
+```bash
+NO_COLOR=1 hctl api list
+HARNESS_COLOR=always hctl api list
+HARNESS_ANIMATION=never hctl account-roles list-roles-acc --limit 10
+HARNESS_STATUS=never hctl account-roles list-roles-acc --limit 10
+HARNESS_TABLE_STYLE=unicode hctl account-roles list-roles-acc --output table
+HARNESS_TABLE_STYLE=plain hctl account-roles list-roles-acc --output table
+HARNESS_ASCII=1 hctl account-roles list-roles-acc --limit 10
+```
+
+Use `HARNESS_ANIMATION=never` to keep the final status line without live
+motion. Use `HARNESS_STATUS=never` when you want no call status on stderr.
+
+## Useful Commands
+
+```bash
+hctl doctor
+hctl --profile prod doctor
+hctl doctor --fix-permissions
+hctl doctor --network
+hctl auth status
+hctl profile list
+hctl profile use prod
+hctl config list
+hctl config set account acc_123
+hctl config set default_output table
+hctl api info
+hctl api groups
+hctl api body create-role-acc
+```
+
+## Development
+
+Refresh the generated endpoint manifest from Harness API docs:
+
+```bash
+uv run python scripts/update_openapi_manifest.py
+```
+
+Run the standard library test suite:
+
+```bash
+uv run python -m unittest
+```
+
+Install development tooling and run checks:
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+uv run ruff format .
+uv run ruff check .
+uv run mypy src/harness_cli
+uv run python scripts/validate_openapi_manifest.py
+uv run python -m compileall -q src tests scripts
+uv build --sdist --wheel
+uv run python scripts/build_standalone.py
+```
+
+Install commit-time formatting hooks:
+
+```bash
+uv run --extra dev pre-commit install
+uv run --extra dev pre-commit run --all-files
+```
+
+The hooks use `uv run --frozen --extra dev ruff format` and
+`uv run --frozen --extra dev ruff check --fix` so everyday commits get the same
+formatter and autofix behavior as CI.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and
+[docs/architecture.md](docs/architecture.md) for the project shape.