Quick Start

The fastest way to connect JFrog CLI to your JFrog Platform instance.

To configure JFrog CLI for your JFrog Platform instance:

1. Add a server configuration (replace placeholders with your actual values):

   Bash

   jf config add myserver \
     --url=https://mycompany.jfrog.io \
     --access-token=<your-access-token> \
     --interactive=false

2. Verify the configuration was saved:

   Bash

   jf config show myserver

3. Set it as the default server for all subsequent commands:

   Bash

   jf config use myserver

4. Test connectivity:

   Bash

   jf rt ping

<your-access-token> is a JFrog Platform access token — a JWT string starting with eyJ. You can generate one under your user profile in the JFrog Platform UI, or use jf access-token-create.

For interactive setup (browser-based, recommended for local development), see Sign In to JFrog Platform via Web.

Sign In to JFrog Platform via Web

Server configurations store connection details for JFrog Platform instances, enabling the JFrog CLI to communicate with Artifactory, Xray, Distribution, and other JFrog services. Configuring a server creates a reusable profile that eliminates the need to provide authentication credentials and URLs with every command.

Use the jf login command to authenticate with the JFrog Platform through a web browser. This command is solely interactive; it does not receive any options and cannot be used in a CI server. Available for Artifactory 7.64.0 and above.

When you run jf login, the CLI first presents an interactive menu where you choose to create a new server entry or select an existing one. After your selection, your default browser opens for authentication. Complete the login in the browser; the CLI receives the resulting token and saves it automatically.

Create Access Tokens

Use this command to create Access Tokens in the JFrog Platform. By default, a user-scoped token is created. Administrators can provide the scope explicitly with --scope, or implicitly with --groups or --grant-admin.

For full syntax, options, and examples, see jf access-token-create.

Configure Servers (add/edit)

The config add or config edit commands add and edit JFrog Platform server configurations, which are stored in JFrog CLI's configuration storage. Other commands can use these configured servers. You can override the configured server details for any command by passing in alternative values for the URL and sign-in credentials. The configured values are saved in a file under the JFrog CLI home directory.

For full options and examples, see jf config add and jf config edit.

📘

Note — How credentials are stored

When you supply --user and --password, the CLI contacts Artifactory's password-encryption API to store an encrypted copy of the password. This requires the credentials to be valid at the time of config add. If you receive a 401 Bad Credentials error during config add, verify your credentials first. In testing environments where you want to store credentials without the encryption API call, use --enc-password=false.

On success, jf config add exits with no output. Run jf config show to verify the configuration was saved.

Remove Configured Servers

The config remove command removes a JFrog Platform server configuration from JFrog CLI's configuration storage.

For full options and examples, see jf config remove.

Show Configured Servers

The config show command shows the stored configuration. To show a specific server's configuration, provide its ID as an argument.

For full details, see jf config show.

Set a Server as Default

The config use command sets a configured server as the default for subsequent commands.

For full details, see jf config use.

Export and Import Configurations

The config export command generates a token that stores a server configuration. The config import command uses this token to import the configuration and save it to JFrog CLI's configuration storage.

For full details, see jf config export and jf config import.

❗️

Important — Scripting with export/import

The token is printed to stdout only. When capturing it in a shell script, suppress stderr separately to avoid corrupting the token. Pass the token as a positional argument to jf config import in the same shell session:

Bash

# Correct: capture stdout only, suppress stderr
TOKEN=$(jf config export <server-id> 2>/dev/null)
# Import on another machine or in the same session
jf config import "$TOKEN"

🚧

Warning

Passing an empty or malformed token to jf config import can overwrite your existing server configurations. Always verify $TOKEN is non-empty before importing.

Encrypt Sensitive Data

File-Based Encryption

Starting from version 1.37.0, JFrog CLI supports encrypting sensitive configuration data using an encryption key stored in a file. To enable encryption:

1. Generate a random 32-character master key. The key must be exactly 32 characters. For example:

   f84hc22dQfhe9f8ydFwfsdn48!wejh8A

2. Create a file named security.yaml under the JFrog CLI security directory (default: ~/.jfrog/security/). If you customized the home directory using the JFROG_CLI_HOME_DIR environment variable, create the file under $JFROG_CLI_HOME_DIR/security/ instead.

3. Add the generated master key to the security.yaml file:

   YAML

   version: 1
   masterKey: "your master key"

4. Ensure that the security.yaml file has only read permissions for the user running JFrog CLI:

   Bash

   chmod 400 ~/.jfrog/security/security.yaml

Sensitive credential fields (passwords and access tokens) are encrypted at the field level within the configuration file the next time JFrog CLI accesses it. Server IDs, URLs, and other non-sensitive fields remain readable. If you have existing configurations, you must reconfigure the servers after enabling encryption.

🚧

Warning

When upgrading JFrog CLI from a version prior to 1.37.0, the ~/.jfrog directory is backed up to ~/.jfrog/backup. After enabling encryption, it is recommended to remove the backup directory to ensure no sensitive data is left unencrypted.

Environment Variable-Based Encryption

Starting from version 2.36.0, JFrog CLI also supports encryption using a key stored in an environment variable. To enable this method:

1. Generate a random 32-character master key. Ensure that the key size is exactly 32 characters. For example:

   f84hc22dQfhe9f8ydFwfsdn48!wejh8A

2. Store the key in an environment variable named JFROG_CLI_ENCRYPTION_KEY.

Sensitive credential fields are encrypted at the field level the next time JFrog CLI accesses the configuration. If you have existing configurations, you must reconfigure the servers.

Disabling Encryption

There is no CLI command to disable encryption once it is enabled. If you remove security.yaml (or unset JFROG_CLI_ENCRYPTION_KEY) while the config file still has the enc flag set, all CLI commands will fail with:

[Error] cannot decrypt config: security configuration file was not found
or the 'JFROG_CLI_ENCRYPTION_KEY' environment variable was not configured

To disable encryption, follow these steps:

1. Restore your master key (re-create security.yaml or set JFROG_CLI_ENCRYPTION_KEY) so the CLI can read existing configs.
2. Note your server IDs by running jf config show.
3. Remove each server: jf config rm <server-id>.
4. Remove the master key (security.yaml or the env var).
5. Manually remove the "enc": true line from ~/.jfrog/jfrog-cli.conf.v6.
6. Re-add your servers with jf config add.

📘

Note

Keep your master key backed up securely. If the key is lost and you can no longer decrypt the config, the only recovery path is the manual editing described above.

Configure Proxy Support

JFrog CLI supports using an HTTP or HTTPS proxy. To configure proxy support, you must set the HTTP_PROXY or HTTPS_PROXY environment variable with the proxy URL.

The HTTP_PROXY , HTTPS_PROXY , and NO_PROXY environment variables are industry standards for proxy configuration.

Configuration Directory Structure

The default configuration directory is ~/.jfrog/. You can change it with the JFROG_CLI_HOME_DIR environment variable. Inside this directory you find:

• config — Server configurations and credentials (JSON format)
• Cached data for plugins and dependencies
• Transfer state data for transfer-files operations

📘

Note

: Do not edit the config file manually when using jf config commands. Manual edits may cause corruption or encryption mismatches.

Multi-Server Support

You can add multiple servers with different IDs. Use jf config use <server-id> to switch the active server. The JFROG_CLI_SERVER_ID environment variable overrides the active server for a single command or session.

Replace <your-access-token> with a valid JFrog Platform access token (a JWT string starting with eyJ). Replace the URLs with your actual JFrog Platform instance URLs.

# Add multiple servers
jf c add dev-server --url=https://acme-dev.jfrog.io --access-token=<your-access-token> --interactive=false
jf c add prod-server --url=https://acme-prod.jfrog.io --access-token=<your-access-token> --interactive=false

# Switch active server
jf c use prod-server

# Or override per-command
jf rt ping --server-id=dev-server

CI/CD Configuration

In CI/CD pipelines, use non-interactive mode:

• Set CI=true to disable interactive prompts
• Add servers with --interactive=false and --url plus --access-token or --password
• Use JFROG_URL and JFROG_ACCESS_TOKEN environment variables as the source of truth
• Add cleanup steps: jf config rm <server-id> --quiet to avoid credential leakage. The --quiet flag suppresses the interactive confirmation prompt, making removal non-interactive.

Boundary Conditions and Limits

Version Compatibility

Stored server configurations are forward-compatible: configs created with older CLI versions work with newer versions. The reverse is not guaranteed — avoid downgrading the CLI after adding configurations.

Enterprise Considerations

TLS and Certificates

For environments with self-signed certificates or custom CA roots:

• Option 1: Add the CA certificate to your system trust store (recommended for production)
• Option 2: Use --insecure-tls on jf config add to skip verification (testing only)
• Option 3: Use --client-cert-path and --client-cert-key-path for mutual TLS (mTLS) authentication

Air-Gapped Environments

In environments without internet access:

1. Download the JFrog CLI binary on a connected machine and copy it to the air-gapped environment
2. Use jf config add with the internal Artifactory URL
3. Set JFROG_CLI_PLUGINS_SERVER and JFROG_CLI_PLUGINS_REPO to resolve plugins from an internal Artifactory repository
4. Set JFROG_CLI_RELEASES_REPO to <server-id>/<repo-name> for Maven/Gradle dependency resolution from an internal source

SSO / External Authentication

JFrog CLI supports Single Sign-On (SSO) through:

• Browser login: jf login opens a browser that supports your SSO provider (SAML, OAuth)
• OIDC token exchange: jf eot exchanges tokens from GitHub Actions, Azure DevOps, or other OIDC providers
• Access tokens: Generate SSO-authenticated tokens through the UI, then use them with --access-token

Troubleshooting

401 Bad Credentials during jf config add

The CLI contacts Artifactory's password-encryption API when storing a username and password. A 401 means the credentials were rejected by Artifactory before any config was saved.

Check:

• Verify your username and password are correct by logging into the JFrog Platform UI.
• If you need to add the config without the encryption API call (for example, in a test environment), use --enc-password=false:
  Bash

  jf config add myserver --url=https://mycompany.jfrog.io \
    --user=<username> --password=<password> \
    --interactive=false --enc-password=false

• Prefer access tokens (--access-token) over username/password for non-interactive use.

cannot decrypt config — CLI refuses to start

This error means encryption was previously enabled (a master key was used at least once) but the key is no longer available.

[Error] cannot decrypt config: security configuration file was not found
or the 'JFROG_CLI_ENCRYPTION_KEY' environment variable was not configured

Fix: Restore the key that was originally used:

• Re-create ~/.jfrog/security/security.yaml with the same 32-character master key, or
• Set export JFROG_CLI_ENCRYPTION_KEY=<your-original-key>.

If the original key is lost, see Disabling Encryption for the manual recovery procedure.

unexpected end of JSON input during jf config import

The Config Token passed to jf config import is empty or corrupted.

Common cause: The token was captured with 2>&1, which mixed log lines from stderr into the token string.

Fix: Capture stdout only when exporting:

TOKEN=$(jf config export <server-id> 2>/dev/null)
[ -n "$TOKEN" ] || { echo "Export failed"; exit 1; }
jf config import "$TOKEN"

🚧

Warning

Passing an empty token to jf config import can silently overwrite your existing server configurations. Always verify $TOKEN is non-empty before running the import.

jf config

Manage JFrog CLI server configurations. Add, edit, show, remove, import, export, and switch between server entries.

Commands

Before You Begin

• What is a server configuration? A server configuration stores the connection details (URL, credentials) for one JFrog Platform instance. You can have multiple configurations for different environments (dev, staging, production).
• Where are configurations stored? In ~/.jfrog/ by default. Override with the JFROG_CLI_HOME_DIR environment variable.
• Do I always need jf config add? No. For one-time use, you can set JFROG_URL and JFROG_ACCESS_TOKEN environment variables instead.