nomadctl 0.2.0__tar.gz

nomadctl-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathaniel Landau
+
+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.

nomadctl-0.2.0/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: nomadctl
+Version: 0.2.0
+Summary: A friendly command-line tool for managing a HashiCorp Nomad homelab cluster.
+Keywords: cli,devops,hashicorp,homelab,nomad,orchestration
+Author: Nathaniel Landau
+Author-email: Nathaniel Landau <github@natelandau.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: httpx2>=2.4.0,<3.0.0
+Requires-Dist: lark>=1.3.1,<2.0.0
+Requires-Dist: msgspec>=0.21.1
+Requires-Dist: nclutils>=3.4.1,<4.0.0
+Requires-Dist: python-hcl2>=8.1.2,<9.0.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.26.7
+Requires-Python: >=3.13, <3.15
+Project-URL: Homepage, https://github.com/natelandau/nd
+Project-URL: Issues, https://github.com/natelandau/nd/issues
+Project-URL: Repository, https://github.com/natelandau/nd
+Description-Content-Type: text/markdown
+
+[![Automated Tests](https://github.com/natelandau/nd/actions/workflows/automated-tests.yml/badge.svg)](https://github.com/natelandau/nd/actions/workflows/automated-tests.yml) [![codecov](https://codecov.io/gh/natelandau/nd/graph/badge.svg?token=HpyhUwExqh)](https://codecov.io/gh/natelandau/nd)
+
+# nd
+
+A friendly command-line tool for managing a Nomad cluster.
+
+`nd` wraps the Nomad HTTP API and the local `nomad` binary behind a small set of
+task-focused commands. Instead of stitching together multiple nomad commands, you
+get easy to remember commands that marry your on-disk job and volume files and the
+live cluster. No more no more hunting for an allocation ID or task name, just use
+your easy to remember job and volume names and the cli does the rest.
+
+## Features
+
+- A one-screen cluster dashboard covering nodes, jobs, allocations, deployments,
+  evaluations, and host volumes.
+- Deploy and stop commands that watch the rollout or drain live and report a clear
+  success or failure at the end.
+- Job-file aware commands that discover and work with your local `.hcl` and `.nomad` specs
+- Interactive shell and log streaming for any task, with a prompt to pick the job,
+  allocation, and task when the choice is ambiguous.
+- Dynamic host volume management: register, delete, and list host volumes across
+  every eligible node.
+- Standard `NOMAD_*` environment variables work out of the box, with an optional
+  config file for anything you would rather not retype.
+
+## Requirements
+
+- Python 3.13 or 3.14.
+- A reachable Nomad cluster.
+- The `nomad` binary on your `PATH`. The `plan`, `run`, `exec`, and `logs` commands
+  shell out to it, because the HTTP API cannot parse HCL2 job files and does not own
+  the interactive exec protocol. The other commands use the API only.
+
+## Installation
+
+The tool is published to PyPI as `nomadctl`. The installed command is `nd`.
+
+Install it as an isolated CLI with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install nomadctl
+```
+
+Or with `pipx`:
+
+```bash
+pipx install nomadctl
+```
+
+Confirm the install:
+
+```bash
+nd --version
+```
+
+## Configuration
+
+`nd` reads the standard Nomad environment variables first, then overrides them with
+an optional config file. If you already run `nomad` from your shell, `nd` targets
+the same cluster with no extra setup.
+
+### Environment variables
+
+| Variable                | Purpose                      | Default                    |
+| ----------------------- | ---------------------------- | -------------------------- |
+| `NOMAD_ADDR`            | Cluster API address          | `http://127.0.0.1:4646`    |
+| `NOMAD_TOKEN`           | ACL token                    | none                       |
+| `NOMAD_NAMESPACE`       | Default namespace            | none                       |
+| `NOMAD_REGION`          | Default region               | none                       |
+| `NOMAD_CACERT`          | Path to a CA certificate     | none                       |
+| `NOMAD_CLIENT_CERT`     | Path to a client certificate | none                       |
+| `NOMAD_CLIENT_KEY`      | Path to a client key         | none                       |
+| `NOMAD_TLS_SERVER_NAME` | TLS server name override     | none                       |
+| `NOMAD_UI_URL`          | Base URL for web UI links    | falls back to `NOMAD_ADDR` |
+
+### Config file
+
+For settings you do not want to export every session, create
+`~/.config/nd/config.toml` (or `$XDG_CONFIG_HOME/nd/config.toml`). Values here
+override the environment.
+
+```toml
+[nomad]
+address = "https://nomad.example.com:4646"
+token   = "your-acl-token"
+ui_url  = "https://nomad.example.com"
+
+# Directories nd searches for .hcl and .nomad job files.
+[jobs]
+directories = ["~/homelab/jobs"]
+
+# Directories nd searches for host volume spec files.
+[volumes]
+directories = ["~/homelab/volumes"]
+```
+
+The `[jobs]` and `[volumes]` directory lists power the file-aware commands. Without
+them, `list`, `plan`, `run`, and the `volume` commands have nothing to discover.
+
+## Quick start
+
+Point `nd` at your cluster, then look at it:
+
+```bash
+export NOMAD_ADDR="https://nomad.example.com:4646"
+export NOMAD_TOKEN="your-acl-token"
+
+nd
+```
+
+Add a job directory to your config file, then list your specs against the live
+cluster:
+
+```bash
+nd list
+```
+
+Deploy a job that is not yet running and watch it roll out:
+
+```bash
+nd run web
+```
+
+Tail its logs, then open a shell inside it:
+
+```bash
+nd logs web
+nd exec web
+```
+
+## Commands
+
+Run `nd --help`, or `nd <command> --help`, for the full option list at any time.
+
+| Command                     | What it does                                                                      |
+| --------------------------- | --------------------------------------------------------------------------------- |
+| `nd status`                 | Show an at-a-glance overview of the cluster. Also runs when you type `nd` alone.  |
+| `nd list`                   | List discovered job files and whether each is running, dead, or not deployed.     |
+| `nd plan [JOB]`             | Preview the changes one or more job files would apply, including to running jobs. |
+| `nd run [JOB]`              | Deploy not-yet-running job files and watch the rollout.                           |
+| `nd stop [JOB]`             | Stop, and optionally purge, running jobs and watch them drain.                    |
+| `nd logs [JOB]`             | Stream, tail, or export a task's logs.                                            |
+| `nd exec [JOB]`             | Open an interactive shell inside a running task.                                  |
+| `nd clean`                  | Force garbage collection and reconcile job summaries.                             |
+| `nd volume register [NAME]` | Register host volumes on every eligible node.                                     |
+| `nd volume delete [NAME]`   | Delete registered host volumes matching the selected specs.                       |
+| `nd volume list [NAME]`     | List host volume specs and where each is registered.                              |
+
+### Targeting jobs by name
+
+Commands that take a `JOB` or `NAME` argument match by case-insensitive name prefix.
+A single match runs straight away; several matches open a prompt. Omit the argument
+to pick from a list of every candidate.
+
+```bash
+nd run web          # runs the one job whose name starts with "web"
+nd stop             # prompts you to choose from all running jobs
+```
+
+### Previewing before you act
+
+Lifecycle commands accept `--dry-run` (`-n`) to report their targets without
+touching the cluster:
+
+```bash
+nd run --dry-run
+nd stop web --dry-run
+nd volume register --dry-run
+```
+
+For `nd run`, a dry run still validates each job file locally, so it catches a
+broken spec without registering anything.
+
+### Deploying jobs
+
+`nd run` only offers jobs that are not already running. Each selected file is
+validated and registered, then watched live until its deployment or allocations
+settle. Use `--detach` to register and return without watching the rollout.
+
+```bash
+nd run                # choose from every deployable job
+nd run web            # deploy the job whose name starts with "web"
+nd run web --detach   # register and return immediately
+```
+
+### Working with logs
+
+`nd logs` streams both stdout and stderr live until you press Ctrl-C. Narrow or
+redirect the output with flags:
+
+```bash
+nd logs web                 # follow stdout and stderr
+nd logs web --stderr        # follow stderr only
+nd logs web --tail 100      # print the last 100 lines, no follow
+nd logs web --export run.log  # write the current logs to a file
+```
+
+### Stopping jobs
+
+`nd stop` confirms before it acts unless you pass `--force`. Use `--purge` to
+garbage-collect the job afterward, `--detach` to return without watching the drain,
+and `--no-shutdown-delay` to skip the configured shutdown delays for an immediate
+teardown.
+
+```bash
+nd stop web                       # confirm, stop, and watch it drain
+nd stop web --purge --force       # purge without a prompt
+nd stop web --detach              # request the stop and return immediately
+```
+
+### Verbosity
+
+Add `-v` for debug output or `-vv` to trace each API request with timings. The flag
+works before or after the subcommand.
+
+```bash
+nd status -v
+nd -vv run web
+```
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) for dependency management and
+[duty](https://pawamoy.github.io/duty/) as a task runner.
+
+```bash
+uv sync                  # install dependencies
+uv run nd --help         # run the CLI from source
+uv run duty lint         # run ruff, ty, typos, and prek
+uv run duty test         # run the test suite with coverage
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

nomadctl-0.2.0/README.md

@@ -0,0 +1,236 @@
+[![Automated Tests](https://github.com/natelandau/nd/actions/workflows/automated-tests.yml/badge.svg)](https://github.com/natelandau/nd/actions/workflows/automated-tests.yml) [![codecov](https://codecov.io/gh/natelandau/nd/graph/badge.svg?token=HpyhUwExqh)](https://codecov.io/gh/natelandau/nd)
+
+# nd
+
+A friendly command-line tool for managing a Nomad cluster.
+
+`nd` wraps the Nomad HTTP API and the local `nomad` binary behind a small set of
+task-focused commands. Instead of stitching together multiple nomad commands, you
+get easy to remember commands that marry your on-disk job and volume files and the
+live cluster. No more no more hunting for an allocation ID or task name, just use
+your easy to remember job and volume names and the cli does the rest.
+
+## Features
+
+- A one-screen cluster dashboard covering nodes, jobs, allocations, deployments,
+  evaluations, and host volumes.
+- Deploy and stop commands that watch the rollout or drain live and report a clear
+  success or failure at the end.
+- Job-file aware commands that discover and work with your local `.hcl` and `.nomad` specs
+- Interactive shell and log streaming for any task, with a prompt to pick the job,
+  allocation, and task when the choice is ambiguous.
+- Dynamic host volume management: register, delete, and list host volumes across
+  every eligible node.
+- Standard `NOMAD_*` environment variables work out of the box, with an optional
+  config file for anything you would rather not retype.
+
+## Requirements
+
+- Python 3.13 or 3.14.
+- A reachable Nomad cluster.
+- The `nomad` binary on your `PATH`. The `plan`, `run`, `exec`, and `logs` commands
+  shell out to it, because the HTTP API cannot parse HCL2 job files and does not own
+  the interactive exec protocol. The other commands use the API only.
+
+## Installation
+
+The tool is published to PyPI as `nomadctl`. The installed command is `nd`.
+
+Install it as an isolated CLI with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install nomadctl
+```
+
+Or with `pipx`:
+
+```bash
+pipx install nomadctl
+```
+
+Confirm the install:
+
+```bash
+nd --version
+```
+
+## Configuration
+
+`nd` reads the standard Nomad environment variables first, then overrides them with
+an optional config file. If you already run `nomad` from your shell, `nd` targets
+the same cluster with no extra setup.
+
+### Environment variables
+
+| Variable                | Purpose                      | Default                    |
+| ----------------------- | ---------------------------- | -------------------------- |
+| `NOMAD_ADDR`            | Cluster API address          | `http://127.0.0.1:4646`    |
+| `NOMAD_TOKEN`           | ACL token                    | none                       |
+| `NOMAD_NAMESPACE`       | Default namespace            | none                       |
+| `NOMAD_REGION`          | Default region               | none                       |
+| `NOMAD_CACERT`          | Path to a CA certificate     | none                       |
+| `NOMAD_CLIENT_CERT`     | Path to a client certificate | none                       |
+| `NOMAD_CLIENT_KEY`      | Path to a client key         | none                       |
+| `NOMAD_TLS_SERVER_NAME` | TLS server name override     | none                       |
+| `NOMAD_UI_URL`          | Base URL for web UI links    | falls back to `NOMAD_ADDR` |
+
+### Config file
+
+For settings you do not want to export every session, create
+`~/.config/nd/config.toml` (or `$XDG_CONFIG_HOME/nd/config.toml`). Values here
+override the environment.
+
+```toml
+[nomad]
+address = "https://nomad.example.com:4646"
+token   = "your-acl-token"
+ui_url  = "https://nomad.example.com"
+
+# Directories nd searches for .hcl and .nomad job files.
+[jobs]
+directories = ["~/homelab/jobs"]
+
+# Directories nd searches for host volume spec files.
+[volumes]
+directories = ["~/homelab/volumes"]
+```
+
+The `[jobs]` and `[volumes]` directory lists power the file-aware commands. Without
+them, `list`, `plan`, `run`, and the `volume` commands have nothing to discover.
+
+## Quick start
+
+Point `nd` at your cluster, then look at it:
+
+```bash
+export NOMAD_ADDR="https://nomad.example.com:4646"
+export NOMAD_TOKEN="your-acl-token"
+
+nd
+```
+
+Add a job directory to your config file, then list your specs against the live
+cluster:
+
+```bash
+nd list
+```
+
+Deploy a job that is not yet running and watch it roll out:
+
+```bash
+nd run web
+```
+
+Tail its logs, then open a shell inside it:
+
+```bash
+nd logs web
+nd exec web
+```
+
+## Commands
+
+Run `nd --help`, or `nd <command> --help`, for the full option list at any time.
+
+| Command                     | What it does                                                                      |
+| --------------------------- | --------------------------------------------------------------------------------- |
+| `nd status`                 | Show an at-a-glance overview of the cluster. Also runs when you type `nd` alone.  |
+| `nd list`                   | List discovered job files and whether each is running, dead, or not deployed.     |
+| `nd plan [JOB]`             | Preview the changes one or more job files would apply, including to running jobs. |
+| `nd run [JOB]`              | Deploy not-yet-running job files and watch the rollout.                           |
+| `nd stop [JOB]`             | Stop, and optionally purge, running jobs and watch them drain.                    |
+| `nd logs [JOB]`             | Stream, tail, or export a task's logs.                                            |
+| `nd exec [JOB]`             | Open an interactive shell inside a running task.                                  |
+| `nd clean`                  | Force garbage collection and reconcile job summaries.                             |
+| `nd volume register [NAME]` | Register host volumes on every eligible node.                                     |
+| `nd volume delete [NAME]`   | Delete registered host volumes matching the selected specs.                       |
+| `nd volume list [NAME]`     | List host volume specs and where each is registered.                              |
+
+### Targeting jobs by name
+
+Commands that take a `JOB` or `NAME` argument match by case-insensitive name prefix.
+A single match runs straight away; several matches open a prompt. Omit the argument
+to pick from a list of every candidate.
+
+```bash
+nd run web          # runs the one job whose name starts with "web"
+nd stop             # prompts you to choose from all running jobs
+```
+
+### Previewing before you act
+
+Lifecycle commands accept `--dry-run` (`-n`) to report their targets without
+touching the cluster:
+
+```bash
+nd run --dry-run
+nd stop web --dry-run
+nd volume register --dry-run
+```
+
+For `nd run`, a dry run still validates each job file locally, so it catches a
+broken spec without registering anything.
+
+### Deploying jobs
+
+`nd run` only offers jobs that are not already running. Each selected file is
+validated and registered, then watched live until its deployment or allocations
+settle. Use `--detach` to register and return without watching the rollout.
+
+```bash
+nd run                # choose from every deployable job
+nd run web            # deploy the job whose name starts with "web"
+nd run web --detach   # register and return immediately
+```
+
+### Working with logs
+
+`nd logs` streams both stdout and stderr live until you press Ctrl-C. Narrow or
+redirect the output with flags:
+
+```bash
+nd logs web                 # follow stdout and stderr
+nd logs web --stderr        # follow stderr only
+nd logs web --tail 100      # print the last 100 lines, no follow
+nd logs web --export run.log  # write the current logs to a file
+```
+
+### Stopping jobs
+
+`nd stop` confirms before it acts unless you pass `--force`. Use `--purge` to
+garbage-collect the job afterward, `--detach` to return without watching the drain,
+and `--no-shutdown-delay` to skip the configured shutdown delays for an immediate
+teardown.
+
+```bash
+nd stop web                       # confirm, stop, and watch it drain
+nd stop web --purge --force       # purge without a prompt
+nd stop web --detach              # request the stop and return immediately
+```
+
+### Verbosity
+
+Add `-v` for debug output or `-vv` to trace each API request with timings. The flag
+works before or after the subcommand.
+
+```bash
+nd status -v
+nd -vv run web
+```
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) for dependency management and
+[duty](https://pawamoy.github.io/duty/) as a task runner.
+
+```bash
+uv sync                  # install dependencies
+uv run nd --help         # run the CLI from source
+uv run duty lint         # run ruff, ty, typos, and prek
+uv run duty test         # run the test suite with coverage
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).