Enterprise JFrog CLI configuration reference

📘
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/. The location can be changed 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.

Configuration File Structure

The ~/.jfrog/config file stores server entries. Each entry has a unique ID and contains URL, authentication method, and optional TLS settings. The format is JSON or a compatible structure.

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 — the configuration must be removed with jf config rm and re-added. 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 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. See Configuring the CLI for both encryption methods.

Multi-Server Support

Multiple servers can coexist under different IDs. The active default is switched 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 config file default.

📘
Note on reference tokens
: If you use a short-lived or SSO-issued reference token (non-JWT format), the CLI will display 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, please provide 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
: This command calls 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 environment variables such as JFROG_URL and JFROG_ACCESS_TOKEN as the source of truth in some setups. A teardown step such as jf config rm <server-id> --quiet reduces the chance of credentials persisting on ephemeral agents.

See JFrog CLI Environment Variables for the complete list of supported CI/CD environment variables, including JFROG_USER, JFROG_PASSWORD, JFROG_CLI_SERVER_ID, and others.

Boundary Conditions and Limits

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	JWT format (starts with `eyJ`) or reference token	JWT tokens 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 BOM (Byte Order Mark). UTF-8 encoding. Unix line endings recommended
Config encryption key	Any string	If set, must be identical across all sessions using 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 in production.

Version Compatibility

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: configs 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’s 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’s built-in proxy configuration.

TLS and Certificates

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

System trust store: CA certificates installed in the OS 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.

See also 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/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

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

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: SSO-authenticated tokens generated through the UI and supplied with --access-token