Quick Start

Connect JFrog CLI to your JFrog Platform instance with the following steps.

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 JSON Web Token (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 the JFrog Platform via web.

Sign in to the 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 you cannot use it on a CI server. Available for Artifactory 7.64.0 or later.

When you run jf login, the JFrog 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 JFrog CLI receives the resulting token and saves it automatically.

Create Access Tokens

Use jf access-token-create 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 more information, see Create access tokens with the JFrog CLI.

Configure Servers (Add or 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 more information, see Add a JFrog CLI server configuration and Edit a JFrog CLI server configuration.

📘

Note

— How credentials are stored

When you supply --user and --password, the JFrog CLI contacts the JFrog Artifactory password-encryption REST API to store an encrypted copy of the password. This requires the credentials to be valid when you run jf config add. If you receive a 401 Bad Credentials error during jf config add, verify your credentials first. In testing environments where you want to store credentials without the encryption REST API request, 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 more information, see Remove JFrog CLI server configurations.

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 more information, see Show stored JFrog CLI server configurations.

Set a Server as Default

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

For more information, see Set the default JFrog CLI server.

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 more information, see Export a JFrog CLI server configuration and Import a JFrog CLI server configuration.

❗️

Important

— Scripting with export/import

The token is printed to standard output only. When you capture it in a shell script, suppress standard error separately so you do not corrupt the token. Pass the token as a positional argument to jf config import in the same shell session.

Bash

# Capture standard output only, suppress standard error
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 you upgrade JFrog CLI from a version prior to 1.37.0, the ~/.jfrog directory is backed up to ~/.jfrog/backup. After enabling encryption, remove the backup directory so 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 JFrog CLI can read existing configurations.
2. Record 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 configuration, the only recovery path is the manual editing described in the preceding steps.

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.

The following table describes proxy-related environment variables.

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:

• jfrog-cli.conf.v6 (under the CLI home directory) — Server configurations and credentials (JSON)
• Cached data for plugins and dependencies
• Transfer state data for transfer-files operations

📘

Note

Do not edit the config file manually when you use 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.

The following example shows multiple servers. 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 continuous integration and continuous delivery (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

The following table lists boundary conditions and limits.

Version Compatibility

The following table summarizes version compatibility.

Stored server configurations are forward-compatible. Configurations created with older JFrog CLI versions work with newer versions. The reverse is not guaranteed. Avoid downgrading JFrog 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 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 and External Authentication

JFrog CLI supports single sign-on (SSO) and OpenID Connect (OIDC) for the following:

• 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 JFrog CLI contacts the JFrog Artifactory password-encryption REST API when storing a username and password. A 401 response means the credentials were rejected by JFrog Artifactory before any configuration was saved.

• Verify credentials. Confirm your username and password by signing in to the JFrog Platform UI.

• Skip encryption when testing. If you need to add the configuration without the encryption REST API request 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. Use --access-token instead of username and 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.
• 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

The following table lists jf config subcommands.

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.