python-jcli 0.1.0__tar.gz

python_jcli-0.1.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: python-jcli
+Version: 0.1.0
+Summary: Python Jenkins CLI tool
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
+Requires-Dist: requests~=2.31.0
+Requires-Dist: pyyaml~=6.0.1
+Requires-Dist: rich>=13.7.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+
+# jcli
+
+A command-line tool for managing Jenkins servers. jcli wraps the Jenkins REST API into readable commands that work the way you'd expect, with table, JSON, and YAML output options.
+
+[中文文档](README-zh.md)
+
+## Features
+
+- **8 command modules** covering jobs, builds, nodes, plugins, credentials, pipelines, views, and system management
+- **Multiple output formats**: human-readable tables (default, via Rich), JSON, and YAML
+- **Multi-profile support** via `~/.jcli/config.yaml` with environment variable overrides
+- **Automatic CSRF (Crumb) handling** for Jenkins servers with CSRF protection enabled
+- **Built with Click and Rich** for a polished terminal experience
+
+## Requirements
+
+- Python 3.10 or later
+- A Jenkins server running Jenkins 2.x or later
+
+## Installation
+
+Install from source with pip:
+
+```bash
+pip install .
+```
+
+Or in editable mode for development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+After installation, `jcli` is available as a console script.
+
+## Quick Start
+
+### 1. Configure your Jenkins connection
+
+Create a configuration file at `~/.jcli/config.yaml`:
+
+```yaml
+active_profile: default
+profiles:
+  default:
+    url: https://jenkins.example.com
+    username: admin
+    api_token: "11abcdef0123456789abcdef0123456789ab"
+    description: "Production Jenkins"
+```
+
+If the file doesn't exist, jcli creates it with a template on first run.
+
+To generate an API token, go to your Jenkins user page: **Your Username > Configure > API Token > Add new Token**.
+
+### 2. Run your first command
+
+```bash
+jcli job list
+```
+
+If your server is configured correctly, this prints a table of all Jenkins jobs.
+
+## Configuration
+
+### Config file
+
+jcli stores profiles in `~/.jcli/config.yaml`. Each profile has four fields:
+
+| Field        | Description                |
+|-------------|----------------------------|
+| `url`       | Jenkins server URL          |
+| `username`  | Jenkins username            |
+| `api_token` | Jenkins API token           |
+| `description` | Human-readable description |
+
+The `active_profile` key selects which profile to use.
+
+To add another server profile, edit the file and add a new entry under `profiles`:
+
+```yaml
+active_profile: prod
+profiles:
+  prod:
+    url: https://jenkins.prod.example.com
+    username: admin
+    api_token: "..."
+    description: "Production"
+  staging:
+    url: https://jenkins.staging.example.com
+    username: admin
+    api_token: "..."
+    description: "Staging"
+```
+
+### Environment variables
+
+Environment variables override config file values. This is useful in CI pipelines.
+
+| Variable          | Overrides           |
+|-------------------|---------------------|
+| `JCLI_URL`        | `url`               |
+| `JCLI_USERNAME`   | `username`          |
+| `JCLI_API_TOKEN`  | `api_token`         |
+| `JCLI_PROFILE`    | `active_profile`    |
+
+Set `JCLI_PROFILE` to select a profile without editing the config file.
+
+### CLI options
+
+Profile and server can also be set with command-line flags:
+
+```bash
+jcli -p staging job list          # use the "staging" profile
+jcli -s https://ci.example.com job list   # override server URL
+jcli -d job list                  # enable debug logging
+```
+
+Run `jcli --help` for the full option list.
+
+## Command Reference
+
+### Global options
+
+Every command accepts these global flags before the subcommand:
+
+```
+-d, --debug                     Enable debug output
+-f, --format [table|json|yaml]  Output format (default: table)
+-p, --profile TEXT              Configuration profile name
+-s, --server TEXT               Jenkins server URL
+```
+
+### job — Manage Jenkins jobs
+
+```
+jcli job list                               List all jobs
+jcli job get JOB_NAME                       Show details for a specific job
+jcli job create JOB_NAME -f job-config.xml  Create a new job from XML config file
+jcli job config JOB_NAME                    Print the XML configuration of a job
+jcli job copy SOURCE_JOB NEW_NAME           Copy a job to a new name
+jcli job enable JOB_NAME                    Enable a disabled job
+jcli job disable JOB_NAME                   Disable a job
+jcli job delete JOB_NAME                    Delete a job
+```
+
+### build — Manage Jenkins builds
+
+```
+jcli build list JOB_NAME                    List recent builds for a job
+jcli build get JOB_NAME BUILD_NUMBER        Show details for a specific build
+jcli build trigger JOB_NAME                 Trigger a new build
+jcli build log JOB_NAME BUILD_NUMBER        Show console log for a build
+jcli build stop JOB_NAME BUILD_NUMBER       Stop a running build
+jcli build queue                            Show the current build queue
+```
+
+### node — Manage Jenkins nodes (agents)
+
+```
+jcli node list                              List all nodes
+jcli node get NODE_NAME                     Get details of a specific node
+jcli node delete NODE_NAME                  Delete a node
+jcli node toggle NODE_NAME --offline        Take a node offline
+jcli node toggle NODE_NAME --online         Bring a node back online
+```
+
+### plugin — Manage Jenkins plugins
+
+```
+jcli plugin list                            List installed plugins
+jcli plugin get PLUGIN_NAME                 Show details for a single plugin
+jcli plugin install PLUGIN_NAME             Install a plugin
+jcli plugin uninstall PLUGIN_NAME           Uninstall a plugin
+```
+
+### credential — Manage Jenkins credentials
+
+```
+jcli credential list                        List credentials
+jcli credential get CREDENTIAL_NAME         Get credential details
+jcli credential create -f cred-config.xml   Create a credential from XML config
+jcli credential delete CREDENTIAL_NAME      Delete a credential
+```
+
+### pipeline — Manage Jenkins pipelines
+
+```
+jcli pipeline stages JOB_NAME BUILD_NUMBER  List stages for a Pipeline build
+jcli pipeline log JOB_NAME BUILD_NUMBER     Get log output for a Pipeline step
+jcli pipeline pending JOB_NAME BUILD_NUMBER Show pending input actions
+jcli pipeline validate -f Jenkinsfile       Validate a Jenkinsfile against the server
+```
+
+### view — Manage Jenkins views
+
+```
+jcli view list                              List all views
+jcli view get VIEW_NAME                     Get details for a view
+jcli view create -f view-config.xml         Create a view from XML config
+jcli view delete VIEW_NAME                  Delete a view
+```
+
+### system — Jenkins system information and management
+
+```
+jcli system info                            Show system version and stats
+jcli system load                            Show queue length and executor counts
+jcli system quiet-down                      Put Jenkins into quiet-down mode
+jcli system cancel-quiet-down               Cancel quiet-down mode
+jcli system restart                         Trigger a safe restart
+jcli system script "println('hello')"       Execute a Groovy script on the server
+```
+
+## Output Formats
+
+jcli supports three output formats, selectable with `-f` / `--format`:
+
+```bash
+jcli -f table job list    # Rich-formatted table (default)
+jcli -f json  job list    # JSON output
+jcli -f yaml  job list    # YAML output
+```
+
+Table mode uses the [Rich](https://github.com/Textualize/rich) library with alternating row colors and auto-width columns. Pipe the output to any file or command as needed.
+
+## Development
+
+### Setup
+
+```bash
+git clone <repo-url> jcli
+cd jcli
+pip install -e ".[dev]"
+```
+
+### Running tests
+
+The test suite uses pytest with the `responses` library for HTTP mocking:
+
+```bash
+pytest
+```
+
+For coverage:
+
+```bash
+pytest --cov=jcli --cov-report=term-missing
+```
+
+### Project structure
+
+```
+jcli/
+  cli.py              Main CLI entry point (Click group)
+  __init__.py         Version
+  plugins/            Command modules (one per Jenkins domain)
+    job.py
+    build.py
+    node.py
+    plugin.py
+    credential.py
+    pipeline.py
+    view.py
+    system.py
+  sdk/                Shared libraries
+    client.py         Jenkins REST API client (HTTP, auth, crumb)
+    config.py         Configuration management (YAML, env vars)
+    output/
+      formatter.py    Table/JSON/YAML output formatting
+    exceptions.py     Typed exceptions
+tests/                pytest test suite
+```
+
+### Dependencies
+
+| Package          | Purpose                     |
+|-----------------|-----------------------------|
+| click >= 8.1.0   | CLI framework               |
+| requests ~= 2.31 | HTTP client                 |
+| pyyaml ~= 6.0.1  | YAML config parsing         |
+| rich >= 13.7.1   | Terminal formatting (tables) |
+| argcomplete >= 3.3 | Shell tab completion       |
+
+Dev dependencies (optional `[dev]` extra):
+
+| Package          | Purpose                     |
+|-----------------|-----------------------------|
+| pytest >= 7.0    | Test runner                 |
+| pytest-cov >= 4.0 | Coverage reporting         |
+| responses >= 0.23 | HTTP response mocking      |
+
+## License
+
+MIT

python_jcli-0.1.0/README.md

@@ -0,0 +1,295 @@
+# jcli
+
+A command-line tool for managing Jenkins servers. jcli wraps the Jenkins REST API into readable commands that work the way you'd expect, with table, JSON, and YAML output options.
+
+[中文文档](README-zh.md)
+
+## Features
+
+- **8 command modules** covering jobs, builds, nodes, plugins, credentials, pipelines, views, and system management
+- **Multiple output formats**: human-readable tables (default, via Rich), JSON, and YAML
+- **Multi-profile support** via `~/.jcli/config.yaml` with environment variable overrides
+- **Automatic CSRF (Crumb) handling** for Jenkins servers with CSRF protection enabled
+- **Built with Click and Rich** for a polished terminal experience
+
+## Requirements
+
+- Python 3.10 or later
+- A Jenkins server running Jenkins 2.x or later
+
+## Installation
+
+Install from source with pip:
+
+```bash
+pip install .
+```
+
+Or in editable mode for development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+After installation, `jcli` is available as a console script.
+
+## Quick Start
+
+### 1. Configure your Jenkins connection
+
+Create a configuration file at `~/.jcli/config.yaml`:
+
+```yaml
+active_profile: default
+profiles:
+  default:
+    url: https://jenkins.example.com
+    username: admin
+    api_token: "11abcdef0123456789abcdef0123456789ab"
+    description: "Production Jenkins"
+```
+
+If the file doesn't exist, jcli creates it with a template on first run.
+
+To generate an API token, go to your Jenkins user page: **Your Username > Configure > API Token > Add new Token**.
+
+### 2. Run your first command
+
+```bash
+jcli job list
+```
+
+If your server is configured correctly, this prints a table of all Jenkins jobs.
+
+## Configuration
+
+### Config file
+
+jcli stores profiles in `~/.jcli/config.yaml`. Each profile has four fields:
+
+| Field        | Description                |
+|-------------|----------------------------|
+| `url`       | Jenkins server URL          |
+| `username`  | Jenkins username            |
+| `api_token` | Jenkins API token           |
+| `description` | Human-readable description |
+
+The `active_profile` key selects which profile to use.
+
+To add another server profile, edit the file and add a new entry under `profiles`:
+
+```yaml
+active_profile: prod
+profiles:
+  prod:
+    url: https://jenkins.prod.example.com
+    username: admin
+    api_token: "..."
+    description: "Production"
+  staging:
+    url: https://jenkins.staging.example.com
+    username: admin
+    api_token: "..."
+    description: "Staging"
+```
+
+### Environment variables
+
+Environment variables override config file values. This is useful in CI pipelines.
+
+| Variable          | Overrides           |
+|-------------------|---------------------|
+| `JCLI_URL`        | `url`               |
+| `JCLI_USERNAME`   | `username`          |
+| `JCLI_API_TOKEN`  | `api_token`         |
+| `JCLI_PROFILE`    | `active_profile`    |
+
+Set `JCLI_PROFILE` to select a profile without editing the config file.
+
+### CLI options
+
+Profile and server can also be set with command-line flags:
+
+```bash
+jcli -p staging job list          # use the "staging" profile
+jcli -s https://ci.example.com job list   # override server URL
+jcli -d job list                  # enable debug logging
+```
+
+Run `jcli --help` for the full option list.
+
+## Command Reference
+
+### Global options
+
+Every command accepts these global flags before the subcommand:
+
+```
+-d, --debug                     Enable debug output
+-f, --format [table|json|yaml]  Output format (default: table)
+-p, --profile TEXT              Configuration profile name
+-s, --server TEXT               Jenkins server URL
+```
+
+### job — Manage Jenkins jobs
+
+```
+jcli job list                               List all jobs
+jcli job get JOB_NAME                       Show details for a specific job
+jcli job create JOB_NAME -f job-config.xml  Create a new job from XML config file
+jcli job config JOB_NAME                    Print the XML configuration of a job
+jcli job copy SOURCE_JOB NEW_NAME           Copy a job to a new name
+jcli job enable JOB_NAME                    Enable a disabled job
+jcli job disable JOB_NAME                   Disable a job
+jcli job delete JOB_NAME                    Delete a job
+```
+
+### build — Manage Jenkins builds
+
+```
+jcli build list JOB_NAME                    List recent builds for a job
+jcli build get JOB_NAME BUILD_NUMBER        Show details for a specific build
+jcli build trigger JOB_NAME                 Trigger a new build
+jcli build log JOB_NAME BUILD_NUMBER        Show console log for a build
+jcli build stop JOB_NAME BUILD_NUMBER       Stop a running build
+jcli build queue                            Show the current build queue
+```
+
+### node — Manage Jenkins nodes (agents)
+
+```
+jcli node list                              List all nodes
+jcli node get NODE_NAME                     Get details of a specific node
+jcli node delete NODE_NAME                  Delete a node
+jcli node toggle NODE_NAME --offline        Take a node offline
+jcli node toggle NODE_NAME --online         Bring a node back online
+```
+
+### plugin — Manage Jenkins plugins
+
+```
+jcli plugin list                            List installed plugins
+jcli plugin get PLUGIN_NAME                 Show details for a single plugin
+jcli plugin install PLUGIN_NAME             Install a plugin
+jcli plugin uninstall PLUGIN_NAME           Uninstall a plugin
+```
+
+### credential — Manage Jenkins credentials
+
+```
+jcli credential list                        List credentials
+jcli credential get CREDENTIAL_NAME         Get credential details
+jcli credential create -f cred-config.xml   Create a credential from XML config
+jcli credential delete CREDENTIAL_NAME      Delete a credential
+```
+
+### pipeline — Manage Jenkins pipelines
+
+```
+jcli pipeline stages JOB_NAME BUILD_NUMBER  List stages for a Pipeline build
+jcli pipeline log JOB_NAME BUILD_NUMBER     Get log output for a Pipeline step
+jcli pipeline pending JOB_NAME BUILD_NUMBER Show pending input actions
+jcli pipeline validate -f Jenkinsfile       Validate a Jenkinsfile against the server
+```
+
+### view — Manage Jenkins views
+
+```
+jcli view list                              List all views
+jcli view get VIEW_NAME                     Get details for a view
+jcli view create -f view-config.xml         Create a view from XML config
+jcli view delete VIEW_NAME                  Delete a view
+```
+
+### system — Jenkins system information and management
+
+```
+jcli system info                            Show system version and stats
+jcli system load                            Show queue length and executor counts
+jcli system quiet-down                      Put Jenkins into quiet-down mode
+jcli system cancel-quiet-down               Cancel quiet-down mode
+jcli system restart                         Trigger a safe restart
+jcli system script "println('hello')"       Execute a Groovy script on the server
+```
+
+## Output Formats
+
+jcli supports three output formats, selectable with `-f` / `--format`:
+
+```bash
+jcli -f table job list    # Rich-formatted table (default)
+jcli -f json  job list    # JSON output
+jcli -f yaml  job list    # YAML output
+```
+
+Table mode uses the [Rich](https://github.com/Textualize/rich) library with alternating row colors and auto-width columns. Pipe the output to any file or command as needed.
+
+## Development
+
+### Setup
+
+```bash
+git clone <repo-url> jcli
+cd jcli
+pip install -e ".[dev]"
+```
+
+### Running tests
+
+The test suite uses pytest with the `responses` library for HTTP mocking:
+
+```bash
+pytest
+```
+
+For coverage:
+
+```bash
+pytest --cov=jcli --cov-report=term-missing
+```
+
+### Project structure
+
+```
+jcli/
+  cli.py              Main CLI entry point (Click group)
+  __init__.py         Version
+  plugins/            Command modules (one per Jenkins domain)
+    job.py
+    build.py
+    node.py
+    plugin.py
+    credential.py
+    pipeline.py
+    view.py
+    system.py
+  sdk/                Shared libraries
+    client.py         Jenkins REST API client (HTTP, auth, crumb)
+    config.py         Configuration management (YAML, env vars)
+    output/
+      formatter.py    Table/JSON/YAML output formatting
+    exceptions.py     Typed exceptions
+tests/                pytest test suite
+```
+
+### Dependencies
+
+| Package          | Purpose                     |
+|-----------------|-----------------------------|
+| click >= 8.1.0   | CLI framework               |
+| requests ~= 2.31 | HTTP client                 |
+| pyyaml ~= 6.0.1  | YAML config parsing         |
+| rich >= 13.7.1   | Terminal formatting (tables) |
+| argcomplete >= 3.3 | Shell tab completion       |
+
+Dev dependencies (optional `[dev]` extra):
+
+| Package          | Purpose                     |
+|-----------------|-----------------------------|
+| pytest >= 7.0    | Test runner                 |
+| pytest-cov >= 4.0 | Coverage reporting         |
+| responses >= 0.23 | HTTP response mocking      |
+
+## License
+
+MIT

python_jcli-0.1.0/jcli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

python_jcli-0.1.0/jcli/__main__.py

@@ -0,0 +1,3 @@
+from jcli.cli import main
+
+main()

python_jcli-0.1.0/jcli/cli.py

@@ -0,0 +1,79 @@
+"""Jenkins CLI - Command line interface for managing Jenkins."""
+
+import logging
+import sys
+
+import click
+
+from jcli import __version__
+from jcli.plugins import register_commands
+
+logger = logging.getLogger("jcli")
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="jcli")
+@click.option(
+    "-f",
+    "--format",
+    "output_format",
+    default="table",
+    type=click.Choice(["table", "json", "yaml"]),
+    help="Output format.",
+)
+@click.option("-p", "--profile", default=None, help="Configuration profile name.")
+@click.option("-s", "--server", default=None, help="Jenkins server URL.")
+@click.option("-d", "--debug", is_flag=True, default=False, help="Enable debug output.")
+@click.pass_context
+def cli(ctx, output_format, profile, server, debug):
+    """Jenkins CLI - Manage Jenkins from the command line."""
+    ctx.ensure_object(dict)
+    ctx.obj["format"] = output_format
+    ctx.obj["profile"] = profile
+    ctx.obj["server"] = server
+    ctx.obj["debug"] = debug
+
+    # Configure debug logging when --debug / -d is set
+    if debug:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(asctime)s %(name)s %(levelname)s %(message)s",
+            stream=sys.stderr,
+        )
+        logger.debug("Debug logging enabled")
+    else:
+        # Ensure WARNING+ level when not in debug mode
+        logging.basicConfig(level=logging.WARNING, stream=sys.stderr)
+
+
+# Register all plugin subcommands
+register_commands(cli)
+
+
+@click.group()
+def completion():
+    """Shell completion support for jcli."""
+    pass
+
+
+@completion.command()
+@click.argument("shell", type=click.Choice(["bash", "zsh", "fish"]))
+def show(shell):
+    """Output shell completion script for the specified shell."""
+    from click.shell_completion import BashComplete, ZshComplete, FishComplete
+
+    shell_cls = {"bash": BashComplete, "zsh": ZshComplete, "fish": FishComplete}
+    complete = shell_cls[shell](cli, {}, "jcli", "_JCLI_COMPLETE")
+    click.echo(complete.source(), nl=False)
+
+
+cli.add_command(completion)
+
+
+def main():
+    """CLI entry point."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()