ngen-japi

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

Installation

Install from PyPI:

pip install ngen-japi

Or install from source:

pip install .

Usage

The japi command provides:

• Jenkins API management commands
• Script execution from bundled scripts

Version

Check the version:

japi --version
# or
japi -V

Login

Save Jenkins credentials for easy access:

japi login

The login command will:

• Prompt for Jenkins URL
• Ask for authentication method (username+token, username+password, or base64)
• Save credentials to ~/.ngen-japi/.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:

japi 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:

japi login                    # Setup Jenkins credentials
japi check                    # Validate connection
japi --version               # Check version
japi jobs                     # List all jobs
japi job my-job               # Get job details
japi job --last-success       # Get last 10 successful jobs
japi job --last-failure       # Get last 10 failed jobs
japi build my-job             # Trigger build
japi build my-job --param REF_NAME=develop REF_TYPE=branch  # Build with parameters
japi build my-job --param=REF_NAME=develop --param=REF_TYPE=branch  # Alternative format
japi get-xml my-job           # Get job XML config
japi create my-job job.xml    # Create job from XML
japi create my-job job.xml --force  # Update existing job
japi delete my-job            # Delete job (with confirmation)
japi delete my-job --force    # Delete job without confirmation
japi plugin list              # List all installed plugins
japi plugin list --format json --output plugins.json  # Export to JSON
japi plugin list --format csv --output plugins.csv   # Export to CSV
japi plugin install git      # Install git plugin
japi plugin uninstall git    # Uninstall git plugin

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:

japi jobs

Get job details:

japi job <job-name>

Get last 10 successful jobs:

japi job --last-success

Get last 10 failed jobs:

japi job --last-failure

Trigger a build:

japi 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:

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

Get build console output:

japi log <job-name> <build-number>

Get job XML configuration:

japi get-xml <job-name>

Create or update job from XML:

japi create <job-name> <xml-file> [--force]

Options:

• --force - Skip confirmation when updating existing job

Delete a job:

japi delete <job-name> [--force]

Options:

• --force - Skip confirmation before deleting job

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

List installed plugins:

japi plugin list [--format json|csv] [--output <file>]

Options:

• --format json|csv - Export format (default: table)
• --output <file> - Output file (optional, defaults to stdout)

Examples:

japi plugin list
japi plugin list --format json
japi plugin list --format json --output plugins.json
japi plugin list --format csv --output plugins.csv

Install plugin(s):

japi plugin install <plugin1> [plugin2] ...

Examples:

japi plugin install git
japi plugin install git docker-workflow

Uninstall plugin(s):

japi plugin uninstall <plugin1> [plugin2] ...

Examples:

japi plugin uninstall git
japi plugin uninstall git docker-workflow

Note: Plugin operations require Jenkins permissions: Overall/Administer or Plugin/Install and Plugin/Uninstall

Credential Management

Manage Jenkins credentials stored in the global credentials store.

List all credentials:

japi cred list

Create a credential (interactive mode):

japi cred create

The interactive mode will prompt you to:

• Select credential type (Username/Password, Secret Text, SSH Key)
• Enter credential ID
• Enter description
• Enter type-specific fields (username, password, secret, private key, etc.)

Create a credential (non-interactive mode):

japi cred create --type <type> --id <id> [options...]

Supported credential types:

• username_password or username-password - Username and password credentials
• secret_text or secret-text - Secret text credentials
• ssh_key or ssh-key - SSH username with private key

Options for username_password:

• --id <id> - Credential ID (required)
• --description <desc> - Description (optional)
• --username <user> - Username (required)
• --password <pass> - Password (required)
• --force - Overwrite existing credential

Options for secret_text:

• --id <id> - Credential ID (required)
• --description <desc> - Description (optional)
• --secret <secret> - Secret text (required)
• --force - Overwrite existing credential

Options for ssh_key:

• --id <id> - Credential ID (required)
• --description <desc> - Description (optional)
• --username <user> - Username (required)
• --private-key <key> - Private key content (required if not using file)
• --private-key-file <file> - Private key file path (required if not using key)
• --passphrase <phrase> - Passphrase for encrypted private key (optional)
• --force - Overwrite existing credential

Examples:

# Interactive mode
japi cred create

# Non-interactive: Username/Password
japi cred create --type username_password --id my-git-cred --username myuser --password mypass --description "Git credentials"

# Non-interactive: Secret Text
japi cred create --type secret_text --id my-token --secret "my-secret-token" --description "API token"

# Non-interactive: SSH Key
japi cred create --type ssh_key --id my-ssh-cred --username deploy --private-key-file ~/.ssh/id_rsa --description "Deployment SSH key"

# Overwrite existing credential
japi cred create --type username_password --id my-cred --username newuser --password newpass --force

Delete a credential:

japi cred delete <credential-id> [--force]

Options:

• --force - Skip confirmation before deleting credential

Examples:

japi cred delete my-cred
japi cred delete my-cred --force

Backup all credentials:

japi cred backup [--file backup.json]

Restore credentials from backup:

japi cred restore [--file backup.json] [--force]

Options:

• --file <file> - Path to the backup JSON file (default: jenkins_credentials_backup.json)
• --force - Overwrite existing credentials with the same ID during restore

Note: Credential operations require Jenkins permissions: Credentials/View, Credentials/Create, Credentials/Delete, or Overall/Administer

Script Execution

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

japi rancher --help
japi rancher version

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

How It Works

1. When you run japi {command}, the CLI dispatcher checks in this order:
   • Built-in commands: Jenkins management commands
   • Scripts: Looks for a script at /usr/local/bin/japi-{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_japi/scripts/ directory with name japi-{your-command}
2. Make sure it's executable: chmod +x ngen_japi/scripts/japi-{your-command}
3. Use it with: japi {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-japi
• PyPI: https://pypi.org/project/ngen-japi/

License

MIT