DOCSEARCHbyAlgolia
Submit Docs

JFrog CLI

repository·master·Indexed 20 days ago

https://github.com/jfrog/jfrog-cli

A command-line tool to automate interactions with JFrog products including Artifactory, Xray, and Mission Control via their REST APIs. It features multithreaded transfers, checksum optimization, and a plugin system. The CLI provides dedicated command sets for managing Artifactory users, groups, and permissions, configuring various build tool package managers (such as Maven, Gradle, NPM, and Pip), and transferring files and configurations between Artifactory instances.

Tokens
18.1K
Snippets
74
Records
100
Agent score
67%

What's inside jfrog-cli

  1. Overview of JFrog CLI

    master

    JFrog CLI is a compact and smart client that provides a simple interface to automate access to Artifactory and Mission Control via their REST APIs. It is designed to simplify automation scripts, making them more readable and maintainable.

    Key efficiency features include:

    • Multithreaded upload and download: Speeds up build processes.
    • Checksum optimization: Reduces redundant file transfers.
    • Wildcards and regular expressions: Simplifies collecting artifacts for upload or download.
    • Dry run mode: Provides a preview of file transfer operations before execution.

  2. Extending JFrog CLI with Plugins

    master

    JFrog CLI supports a plugin system that allows users to enhance functionality to meet specific organizational needs.

    • Plugin Implementation: Plugins are maintained as open-source Go projects on GitHub.
    • Plugin Registry: Public plugins are registered in the JFrog CLI Plugins Registry, hosted in the jfrog-cli-plugins-reg repository.
    • Development: Developers are encouraged to create and share plugins. For technical details on building plugins, consult the JFrog CLI Plugin Developer Guide.

  3. How to use external resources in a plugin

    master

    If your plugin requires external files (executables, config files, etc.), you can package them within the plugin.

    Packaging Resources

    1. Create a directory named resources at the root of your plugin's source code.
    2. Place your files inside this directory (you can use subdirectories).
    3. When the plugin is published and installed, these files are automatically downloaded to the plugin's resource directory.

    Accessing Resources in Go Code

    During development, resources are located in plugins/<my-plugin-name>/resources/. When installed, they reside in the same location under the JFrog CLI home directory. Use the jfrog-cli-core utility to resolve the path:

    import (
    "github.com/jfrog/jfrog-cli-core/v2/utils/coreutils"
)

// ...

dir, err := coreutils.GetJfrogPluginsResourcesDir("my-plugin-name")

  4. Scan code and software packages for vulnerabilities

    master

    You can perform security scans using the JFrog CLI from your terminal or via IDE extensions.

    Terminal Commands

    • Project Dependencies: Scan dependencies within your current project directory using jf audit.
    • Local Files/Packages: Scan a specific directory or package on your machine using jf scan <path>.
    • Docker Images: Scan local Docker images using jf docker scan <image name>:<image tag>.

    IDE Integration

    For VS Code, IntelliJ IDEA, WebStorm, PyCharm, Android Studio, or GoLand, you can install the JFrog extension or plugin to view the JFrog panel directly within your IDE.

    # Scan project dependencies
jf audit

# Scan a local path or package
jf scan path/to/dir/or/package

# Scan a local docker image
jf docker scan <image name>:<image tag>

  5. How to include a plugin in the official registry

    master

    To make your plugin publicly available via jf plugin install <name>, you must submit a pull request to the JFrog CLI Plugins Registry.

    Submission Requirements

    • Descriptor File: Create a YAML file named your-plugin-name.yml in the plugins/ directory of the registry repository.
    • Code Structure: Use the commands package pattern (one file per command) as seen in the template.
    • Testing: The registry runs go vet -v ./... && go test -v ./... to verify your plugin. Ensure your code includes thorough tests.
    • Formatting: Run go fmt ./... on your source code.
    • Naming: Use only lowercase characters, numbers, and dashes (max 30 characters).
    • Versioning: Use semantic versioning with a v prefix (e.g., v1.0.0). Verify this by running ./your-plugin -v.
    • Documentation: Include a README.md in your repository root.

    Descriptor File Format

    Your .yml file must follow this structure:

    # Mandatory
pluginName: hello-frog
version: v1.0.0
repository: https://github.com/my-org/my-amazing-plugin
maintainers:
    - github-username1
    - github-username2

# Optional
relativePath: build-info-analyzer
branch: my-release-branch
# OR
tag: my-release-tag
    # Mandatory:
pluginName: hello-frog
version: v1.0.0
repository: https://github.com/my-org/my-amazing-plugin
maintainers:
    - github-username1
    - github-username2

# Optional:
relativePath: build-info-analyzer
branch: my-release-branch
# Note: Use either 'branch' or 'tag', not both.

  6. Install the JFrog CLI

    master

    Install the JFrog CLI using the following commands based on your operating system.

    Linux / MacOS Use curl to run the setup script:

    Windows Use PowerShell to download the executable to your system directory and then run the setup command:

    # Linux / MacOS
curl -fL https://getcli.jfrog.io/setup | sh
    # Windows
powershell "Start-Process -Wait -Verb RunAs powershell '-NoProfile iwr https://releases.jfrog.io/artifactory/jfrog-cli/v2-jf/[RELEASE]/jfrog-cli-windows-amd64/jf.exe -OutFile $env:SYSTEMROOT\system32\jf.exe'" ; jf setup

  8. Test a plugin locally before publishing

    master

    To test a plugin locally without publishing it, you can manually place the binary in the JFrog CLI plugins directory.

    1. Locate your JFrog CLI home directory (usually ~/.jfrog/).
    2. Place your plugin executable in the following path: plugins/<my-plugin-name>/bin/<executable>
    3. If your plugin uses external resources, place them in: plugins/<my-plugin-name>/resources/
    4. Run jf to verify the plugin is recognized and working.

  9. Develop a JFrog CLI Plugin

    master

    JFrog CLI Plugins allow you to extend the CLI's functionality. Plugins are written in Go and can depend on the jfrog-cli-core module to access the underlying CLI codebase.

    Prerequisites

    • Go 1.17 or above (must be in your system PATH).
    • git (must be in your system PATH).

    Quickstart: Build and Run a Template Plugin

    1. Use the official plugin template to start your project.
    2. Clone the template:
      git clone https://github.com/jfrog/jfrog-cli-plugin-template.git
    3. Build and test the executable:
      cd jfrog-cli-plugin-template
go build -o hello-frog
./hello-frog --help
./hello-frog hello --help
./hello-frog hello Yey!
    $ git clone https://github.com/jfrog/jfrog-cli-plugin-template.git
$ cd jfrog-cli-plugin-template
$ go build -o hello-frog
$ ./hello-frog --help

  10. Set up a private JFrog CLI Plugins Registry

    master

    You can host a private registry on an Artifactory server using a local generic repository. This allows your organization to manage internal plugins.

    Setup Steps

    1. Create Repository: In Artifactory, create a local generic repository named jfrog-cli-plugins.
    2. Configure CLI: Ensure your Artifactory server is configured in JFrog CLI using jf c show or jf c add.
    3. Set Environment Variables:
      • JFROG_CLI_PLUGINS_SERVER: Set this to the ID of your configured Artifactory server.
      • JFROG_CLI_PLUGINS_REPO: (Optional) Set this if your repository name is different from jfrog-cli-plugins.

    Publishing to Private Registry

    From your plugin's source root, run:

    jf plugin publish <plugin-name> <plugin-version>

    This command builds the plugin for all supported operating systems and uploads the binaries to your registry.

    jf plugin publish the-plugin-name the-plugin-version