Enterprise JFrog CLI Configuration Reference

📘
Reference guide
This page is a reference guide. For a step-by-step walkthrough of adding and managing server configurations, follow the Manage Server Configurations tutorial.

Configuration Directory Structure

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

jfrog-cli.conf.v6 — 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 using jf config commands. Manual edits may cause corruption or encryption mismatches.

Configuration File Structure

The ~/.jfrog/jfrog-cli.conf.v6 file (or the same filename under the directory from JFROG_CLI_HOME_DIR) stores server entries. Each entry has a unique ID and contains URL, authentication method, and optional TLS settings. The format is JSON.

Configuration Encryption

JFROG_CLI_ENCRYPTION_KEY, when set to a stable value, causes stored passwords and tokens to be encrypted. The same key must be present in the environment before adding a configuration and whenever commands need to read that configuration.

🚧
Warning
If you set JFROG_CLI_ENCRYPTION_KEY when adding a configuration, you must set the same key every time you use that configuration. If you lose the encryption key, the stored credentials cannot be recovered. You must remove the configuration with jf config rm and re-add it. For a guided procedure, see JFrog CLI environment variables.

Illustrative sequence (encryption key, add server, verify, remove):

# Encryption key exported in the shell session
export JFROG_CLI_ENCRYPTION_KEY=<encryption-key>

# Server entry added non-interactively. Credentials stored encrypted
jf config add <server-id> --url=<your-server-url> --access-token=<Token> --interactive=false

Where:

<encryption-key>: A strong, stable secret (see the environment variables reference for length requirements when using the CLI encryption feature).
<server-id>: Chosen server ID.
<your-server-url>: JFrog Platform URL.
<Token>: Access token. Never commit real values.

# Same key required for subsequent commands that read the config
export JFROG_CLI_ENCRYPTION_KEY=<encryption-key>
jf rt ping --server-id=<server-id>

jf config rm <server-id> --quiet

Where:

<server-id>: Server ID to remove.

File-based encryption is also available. For more information, see Configuring the CLI for both encryption methods.

Multi-Server Support

Multiple servers can coexist under different IDs. You switch the active default with jf config use <server-id>. The JFROG_CLI_SERVER_ID environment variable overrides the active server for a single command or session without rewriting the configuration file default.

📘
Note
on reference tokens
If you use a short-lived or single sign-on (SSO)-issued reference token (non-JWT format), the CLI displays the following warning when adding the configuration. This is expected, and the configuration is still created successfully:
[Warn] couldn't extract payload from Access Token.
The provided access token is not a valid JWT, probably a reference token.
Some package managers only support basic authentication which requires also a username.
If you plan to work with one of those package managers, supply a username.
Package manager integrations that require basic authentication often need --user=<username> on jf config add in addition to the token.

Illustrative multi-server commands:

jf config add dev-server --url=https://dev.jfrog.io --access-token=<Token> --interactive=false
jf config add prod-server --url=https://prod.jfrog.io --access-token=<Token> --interactive=false
jf config use prod-server
# [Info] Using server ID 'prod-server' (https://prod.jfrog.io/)
jf config show
jf rt ping --server-id=dev-server
# OK
jf config rm dev-server --quiet
jf config rm prod-server --quiet

Where:

<Token>: Placeholder for a real token. Do not log or commit.

📘
Note
on jf rt ping
The jf rt ping command sends a request to the /artifactory/api/system/ping endpoint. It returns OK when Artifactory responds correctly. If the configured URL does not point to an Artifactory instance (for example, a typo or a load balancer landing page), the command may still exit 0 if the server returns any HTTP 200 response. Always verify the Artifactory URL includes the correct hostname for your instance.

CI/CD Configuration

Typical automation patterns include non-interactive mode (CI=true disables prompts), server entries created with --interactive=false together with --url and --access-token or --password, and credentials stored in environment variables (for example, JFROG_URL and JFROG_ACCESS_TOKEN) that you pass into jf config add or expand into command flags. A teardown step such as jf config rm <server-id> --quiet reduces the chance of credentials persisting on ephemeral agents.

For more information, see JFrog CLI Environment Variables for variables documented in the CLI (for example CI, JFROG_CLI_SERVER_ID, and JFROG_CLI_ENCRYPTION_KEY).

Boundary Conditions and Limits

The following table lists parameter constraints and related notes.

Parameter	Constraint	Notes
Server ID	Must not be `delete`, `use`, `show`, or `clear`	These are reserved words used by the CLI internally. The CLI returns an error if you attempt to add a server with a reserved ID.
Server ID characters	Alphanumeric, hyphens, and underscores recommended	Avoid spaces, dots, and special characters to prevent shell escaping issues
URL format	Must include protocol (`https://` or `http://`)	Omitting the protocol causes connection failures. Always use `https://` for production
URL trailing slash	Optional	The CLI handles both `https://acme.jfrog.io` and `https://acme.jfrog.io/`
Access token	JSON Web Token (JWT) format (starts with `eyJ`) or reference token	JWTs are 500–2000 characters. Reference tokens (non-JWT, short-lived) are also supported. The CLI displays a `[Warn]` about JWT extraction but proceeds normally. For package manager integrations with reference tokens, also provide `--user`.
Password with special chars	Must be quoted in shell	Use `--password-stdin` or `--access-token-stdin` to avoid shell interpretation issues
CSV file for users-create	Headers must be: `username,password,email`	No byte order mark (BOM). UTF-8 encoding. Unix line endings recommended
Config encryption key (`JFROG_CLI_ENCRYPTION_KEY`)	Exactly 32 characters	If set, must be identical across all sessions that read the encrypted config
`--build-name`	Required with `--build-number`	Both must be present or both absent. Partial specification causes an error
Wildcard patterns	`*` matches any sequence, `?` matches single character	Used in `--include-repos`, `--exclude-repos`, `--exclusions` flags
`--client-cert-path`	Path to a PEM-format client certificate file	Used with `jf config add` for mutual TLS (mTLS). File must be readable by the CLI process.
`--client-cert-key-path`	Path to the private key matching `--client-cert-path`	Must correspond to the certificate's private key. Both flags must be provided together.
`--insecure-tls`	Boolean flag, no value required	Skips TLS certificate verification. Use for testing only. Never use it in production.

Version Compatibility

The following table summarizes minimum versions and related notes.

CLI Version	Minimum Artifactory	Notes
v2.x (current)	7.x	Current version
`jf login`	7.64.0+	Browser-based login requires this minimum
`--reference` token	7.38.10+	Reference tokens require this minimum
Transfer commands	7.x (both source and target)	data-transfer plugin must match server version

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

Enterprise Considerations

Proxy Configuration

Organizations that route outbound traffic through a forward proxy generally export standard proxy variables before CLI use. The JFrog CLI respects Go HTTP proxy environment variables. Example values:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.example.com

For transfer-files operations, the --proxy-key flag can route traffic through Artifactory built-in proxy configuration.

TLS and Certificates

Deployments with self-signed certificates or private certificate authorities commonly use one of the following approaches:

System trust store: CA certificates installed in the operating system or container trust store (preferred for production).
--insecure-tls on jf config add: Skips TLS verification (testing only).
--client-cert-path and --client-cert-key-path: Mutual TLS (mTLS) authentication.

For more information, see Authentication — RSA Keys and Client Certificates for detailed mTLS and SSH key setup.

Air-Gapped Environments

Air-gapped sites usually obtain the CLI binary from a connected staging area, point jf config add at an internal Artifactory URL, and set JFROG_CLI_PLUGINS_SERVER, JFROG_CLI_PLUGINS_REPO, and JFROG_CLI_RELEASES_REPO so plugins and Maven or Gradle dependencies resolve from internal repositories rather than the public internet.

# Internal Artifactory mirrors for plugins and releases
export JFROG_CLI_PLUGINS_SERVER=my-internal-server
export JFROG_CLI_PLUGINS_REPO=jfrog-cli-plugins
export JFROG_CLI_RELEASES_REPO=my-internal-server/jfrog-releases

In this example, my-internal-server is the server ID configured with jf config add, and jfrog-cli-plugins and jfrog-releases are repository keys that mirror the JFrog distribution content.

SSO and External Authentication

JFrog CLI supports SSO through:

Browser login: jf login opens a browser that supports your SSO provider (SAML, OAuth)
OpenID Connect (OIDC) token exchange: jf eot exchanges tokens from GitHub Actions, Azure DevOps, or other OIDC providers
Access tokens: SSO-authenticated tokens generated through the UI and supplied with --access-token