ngen-j

Jenkins API management CLI tool that also supports executing scripts from /usr/local/bin/ngen-j-*.

Installation

Install from PyPI:

pip install ngen-j

Or install from source:

pip install .

Usage

The ngen-j command provides:

• Jenkins API management commands
• Script execution from bundled scripts

Version

Check the version:

ngen-j --version
# or
ngen-j -V

Login

Save Jenkins credentials for easy access:

ngen-j login

The login command will:

• Prompt for Jenkins URL
• Ask for authentication method (username+token, username+password, or base64)
• Save credentials to ~/.ngen-j/.env
• Test the connection

After login, you can use Jenkins commands without setting environment variables each time.

Check Connection

Validate your Jenkins access and credentials:

ngen-j check

The check command will:

• Test connection to Jenkins server
• Verify authentication credentials
• Display Jenkins version and basic info
• Show troubleshooting tips if connection fails

Examples:

ngen-j login                    # Setup Jenkins credentials
ngen-j check                    # Validate connection
ngen-j --version               # Check version
ngen-j jobs                     # List all jobs
ngen-j job my-job               # Get job details
ngen-j job --last-success       # Get last 10 successful jobs
ngen-j job --last-failure       # Get last 10 failed jobs
ngen-j build my-job             # Trigger build
ngen-j build my-job --param REF_NAME=develop REF_TYPE=branch  # Build with parameters
ngen-j build my-job --param=REF_NAME=develop --param=REF_TYPE=branch  # Alternative format
ngen-j get-xml my-job           # Get job XML config
ngen-j create my-job job.xml    # Create job from XML
ngen-j create my-job job.xml --force  # Update existing job
ngen-j delete my-job            # Delete job (with confirmation)
ngen-j delete my-job --force    # Delete job without confirmation

Jenkins API Management

Manage Jenkins jobs and builds using environment variables for authentication.

Environment Variables

Set the following environment variables for Jenkins authentication:

export JENKINS_URL="https://jenkins.example.com"
export JENKINS_USER="your-username"
export JENKINS_TOKEN="your-api-token"

Alternatively, you can use base64 encoded authentication:

export JENKINS_URL="https://jenkins.example.com"
export JENKINS_AUTH="base64-encoded-user:token"

Jenkins Commands

List all jobs:

ngen-j jobs

Get job details:

ngen-j job <job-name>

Get last 10 successful jobs:

ngen-j job --last-success

Get last 10 failed jobs:

ngen-j job --last-failure

Trigger a build:

ngen-j build <job-name> [--param KEY=VALUE ...] or [--param=KEY=VALUE ...]

Options:

• --param KEY=VALUE - Pass build parameters (can be used multiple times)
• --param=KEY=VALUE - Alternative format for build parameters

Examples:

ngen-j build my-job
ngen-j build my-job --param REF_NAME=develop REF_TYPE=branch
ngen-j build my-job --param=REF_NAME=develop --param=REF_TYPE=branch
ngen-j build my-job --param REF_NAME=develop --param=REF_TYPE=branch --param DEPLOY_ENV=staging

Get build console output:

ngen-j log <job-name> <build-number>

Get job XML configuration:

ngen-j get-xml <job-name>

Create or update job from XML:

ngen-j create <job-name> <xml-file> [--force]

Options:

• --force - Skip confirmation when updating existing job

Delete a job:

ngen-j delete <job-name> [--force]

Options:

• --force - Skip confirmation before deleting job

Note: Requires Jenkins permissions: Job/Create, Job/Update, Job/Configure, Job/Delete

Script Execution

If you have a bundled script, you can execute it directly:

ngen-j rancher --help
ngen-j rancher version

The CLI will look for scripts in the bundled scripts directory.

How It Works

1. When you run ngen-j {command}, the CLI dispatcher checks in this order:
   • Built-in commands: Jenkins management commands
   • Scripts: Looks for a script at /usr/local/bin/ngen-j-{command} or bundled scripts
2. If found, it executes the command with any additional arguments passed
3. Scripts can be any executable file (bash, sh, Python, or binary)

Adding New Commands

Scripts

1. Place a script in the ngen_j/scripts/ directory with name ngen-j-{your-command}
2. Make sure it's executable: chmod +x ngen_j/scripts/ngen-j-{your-command}
3. Use it with: ngen-j {your-command}

Development

Building the Package

python -m build

Publishing to PyPI

Menggunakan script otomatis:

./publish.sh --test      # Publish ke Test PyPI
./publish.sh --publish   # Publish ke PyPI production

Atau manual:

python -m build
python -m twine check dist/*
python -m twine upload dist/*

Untuk panduan lengkap, lihat PUBLISH.md.

Repository

• GitHub: https://github.com/mamatnurahmat/ngen-j
• PyPI: https://pypi.org/project/ngen-j/

License

MIT