Use APT with JFrog CLI

Use JFrog CLI to configure APT for a JFrog Artifactory Debian repository and run native APT operations with Artifactory authentication. APT support is available in JFrog CLI 2.118.0 and later.

This topic covers the following tasks:

• Configure Persistent APT Access
• Run APT Operations
• Collect Build-Info for an APT Install
• Remove JFrog-Managed APT Configuration

When to Use

Use jf setup apt when you want native apt-get commands to use an Artifactory Debian repository across terminal sessions. The command creates a persistent source entry and an APT pinning file.

Use jf apt for either of these workflows:

• Run a one-off apt-get operation against Artifactory by passing --repo and --dist. JFrog CLI creates a temporary source file for the operation and removes it afterward.
• Use a source previously created by jf setup apt without passing the repository and distribution on every command.

jf apt doesn't upload .deb files. To publish a .deb file and record Debian artifact details (distribution, component, and architecture), use jf rt upload with --deb <DISTRIBUTION>/<COMPONENT>/<ARCHITECTURE>. For more information, see Upload Files. For repository creation, layouts, and Debian metadata behavior, see Debian Repositories.

After a successful jf apt install, you can collect dependency build-info locally with --build-name and --build-number, then publish that record with jf rt build-publish. For more information, see Collect Build-Info for an APT Install.

Prerequisites

• JFrog CLI 2.118.0 or later installed on a Debian or Ubuntu host.
• Native APT tools installed. jf apt invokes apt-get by default and can explicitly invoke apt-cache or dpkg-query.
• A configured JFrog server. Run jf config add or jf c add, then use the default server or pass --server-id. For more information, see Configure JFrog CLI.
• An Artifactory Debian repository. Use a virtual repository for package resolution so you can resolve dependencies through one URL.
• Required host privileges. Writing under /etc/apt/, updating package indexes, and installing packages normally require root privileges. If you use sudo, ensure that the elevated process can access the intended JFrog CLI server configuration. You can configure the same server for root or pass supported connection options to jf setup apt.
• A repository signing key, unless you intentionally use --trusted in a test environment.

Configure Persistent APT Access

jf setup apt creates a persistent APT source for an Artifactory Debian repository. It also creates an APT preference with pin priority 1001, which makes a package from the selected Artifactory host take precedence when that host contains the package.

Setup Command Synopsis

jf setup apt uses the following command syntax.

sudo jf setup apt \
  [--server-id=<SERVER_ID>] \
  --repo=<REPO_KEY> \
  --dist=<DISTRIBUTION> \
  [--component="<COMPONENT_LIST>"] \
  [--import-key | --trusted]

Where:

• <SERVER_ID>: JFrog CLI server ID from jf config add
• <REPO_KEY>: Artifactory Debian repository key
• <DISTRIBUTION>: Debian or Ubuntu distribution codename, such as bookworm, jammy, or noble
• <COMPONENT_LIST>: One or more space-separated Debian components. The default is main

Setup Options

The following table describes the jf setup apt options.

You can also provide connection flags accepted by jf setup, including --url, --user, --password, and --access-token. Prefer a named server configuration so credentials are managed consistently with other JFrog CLI commands.

To configure persistent APT access:

1. Complete the procedure that matches your environment:

   • Configure with GPG Verification for a signed production repository
   • Configure Multiple Components when you need more than the main component
   • Configure Interactively when you prefer prompts
   • Test Without a Signing Key only for an unsigned test repository

Configure with GPG Verification

Use --import-key for a signed repository.

To configure persistent APT access with GPG verification:

1. Run:

   Shell

   sudo jf setup apt \
     --server-id=<SERVER_ID> \
     --repo=<REPO_KEY> \
     --dist=<DISTRIBUTION> \
     --component=<COMPONENT> \
     --import-key

   Where:

   • <SERVER_ID>: JFrog CLI server ID from jf config add
   • <REPO_KEY>: Artifactory Debian repository key
   • <DISTRIBUTION>: Debian or Ubuntu distribution codename
   • <COMPONENT>: Debian component. The default is main

   For example:

   Shell

   sudo jf setup apt \
     --server-id=my-server \
     --repo=debian-virtual \
     --dist=bookworm \
     --component=main \
     --import-key

   Expected output includes:

   Text

   Installed GPG public key at /etc/apt/keyrings/jfrog-debian-virtual-bookworm.asc
   Wrote /etc/apt/sources.list.d/jfrog-debian-virtual-bookworm.list
   Successfully configured apt to use JFrog Artifactory repository 'debian-virtual'.

JFrog CLI reads the repository configuration to identify its primary signing key. If no named primary key is available, the CLI requests the default Artifactory GPG public key. The source entry uses signed-by so trust is scoped to that repository source.

If you run setup again without --import-key and the matching key file still exists, JFrog CLI reuses that key. Pass --import-key again to refresh it.

Configure Multiple Components

Pass components as one quoted, space-separated value.

To configure multiple Debian components:

1. Run:

   Shell

   sudo jf setup apt \
     --repo=<REPO_KEY> \
     --dist=<DISTRIBUTION> \
     --component="<COMPONENT_LIST>" \
     --import-key

   Where:

   • <REPO_KEY>: Artifactory Debian repository key
   • <DISTRIBUTION>: Debian or Ubuntu distribution codename
   • <COMPONENT_LIST>: Space-separated Debian components

   For example:

   Shell

   sudo jf setup apt \
     --repo=debian-virtual \
     --dist=bookworm \
     --component="main contrib non-free" \
     --import-key

Configure Interactively

To configure APT interactively:

1. Run the command without --repo or --dist in an interactive terminal:

   Shell

   sudo jf setup apt

   JFrog CLI prompts for a virtual Debian repository and a distribution. When --dist is omitted in an interactive terminal, it also prompts for a component and GPG mode. The GPG prompt accepts import, trusted, or an empty value that writes no signed-by or trusted=yes option. Use import for a signed production repository.

In CI or another non-interactive environment, pass both --repo and --dist. Also pass --component and --import-key explicitly when you require those settings.

Generated Files

For repository <REPO_KEY> and distribution <DISTRIBUTION>, setup manages these files.

After writing a changed source, JFrog CLI runs apt-get update against that source file only. It then runs a full apt-get update. If another configured APT source fails during the full refresh, setup still succeeds and JFrog CLI logs a warning. Re-running setup with an identical source is idempotent and reports that no changes are needed.

Test Without a Signing Key

If a test repository isn't signed, you can explicitly disable signature verification.

To skip signature verification in a test environment:

1. Run:

   Shell

   sudo jf setup apt \
     --repo=<REPO_KEY> \
     --dist=<DISTRIBUTION> \
     --trusted

   Where:

   • <REPO_KEY>: Artifactory Debian repository key
   • <DISTRIBUTION>: Debian or Ubuntu distribution codename

   For example:

   Shell

   sudo jf setup apt \
     --repo=debian-test-virtual \
     --dist=bookworm \
     --trusted

--trusted generates a source with trusted=yes. Don't use it for production repositories.

Run APT Operations

jf apt forwards standard input, output, and errors to the native tool. For most arguments, it runs apt-get.

Run Command Synopsis

jf apt uses the following command syntax.

jf apt <APT_GET_COMMAND> <ARGS> <JFROG_OPTIONS>
jf apt apt-cache <ARGS> <JFROG_OPTIONS>
jf apt dpkg-query <ARGS> <JFROG_OPTIONS>

Where:

• <APT_GET_COMMAND>: An apt-get operation such as install, upgrade, remove, or download
• <ARGS>: Native arguments and options passed to the selected APT tool after JFrog-specific options are removed
• <JFROG_OPTIONS>: JFrog CLI flags such as --repo, --dist, --trusted, --skip-login, --from-file, --build-name, and --build-number

jf apt-get is an alias for jf apt.

Arguments

The following table describes the jf apt arguments.

APT Options

The following table describes the JFrog-specific jf apt options.

To run APT operations:

1. Complete the procedure that matches your workflow:

   • Run a One-Off Operation for a temporary Artifactory source
   • Use Persistent Setup after jf setup apt
   • Use Existing System Configuration to skip temporary authentication
   • Run Read-Only Queries for apt-cache or dpkg-query

Run a One-Off Operation

Pass both --repo and --dist with a valid default or explicit server configuration to create a temporary authenticated source.

The one-off source doesn't support --import-key and doesn't add signed-by. Use this mode only when the repository key is already trusted by APT, or pass --trusted in an isolated test environment. For production with repository-scoped signature verification, first run jf setup apt --import-key, then use the persistent workflow without --repo and --dist.

To run a one-off APT install in a test environment:

1. Run:

   Shell

   sudo jf apt install <PACKAGE> \
     --server-id=<SERVER_ID> \
     --repo=<REPO_KEY> \
     --dist=<DISTRIBUTION> \
     --component=<COMPONENT> \
     --trusted

   Where:

   • <PACKAGE>: Debian package name to install
   • <SERVER_ID>: JFrog CLI server ID from jf config add
   • <REPO_KEY>: Artifactory Debian repository key
   • <DISTRIBUTION>: Debian or Ubuntu distribution codename
   • <COMPONENT>: Debian component. The default is main

   For example:

   Shell

   sudo jf apt install curl \
     --server-id=my-server \
     --repo=debian-virtual \
     --dist=bookworm \
     --component=main \
     --trusted

For the temporary operation, JFrog CLI replaces the main source list with the temporary Artifactory source and disables the system sources.list.d directory. The selected Artifactory repository must therefore provide the requested packages and their dependencies.

Before install, upgrade, dist-upgrade, full-upgrade, or satisfy, JFrog CLI runs apt-get update against the temporary source. Other apt-get operations run without that automatic update.

Use Persistent Setup

After jf setup apt, you can omit --repo and --dist.

To install a package using persistent APT setup:

1. Run:

   Shell

   sudo jf apt install <PACKAGE>

   Where:

   • <PACKAGE>: Debian package name to install

   For example:

   Shell

   sudo jf apt install curl

JFrog CLI detects a managed jfrog-*.list file and lets native apt-get use the persistent system configuration.

Use Existing System Configuration

Use --skip-login to bypass temporary source creation.

To skip temporary Artifactory authentication:

1. Run:

   Shell

   sudo jf apt install <PACKAGE> --skip-login

   Where:

   • <PACKAGE>: Debian package name to install

   For example:

   Shell

   sudo jf apt install curl --skip-login

If you omit --repo and --dist and no persistent JFrog source exists, the command warns and runs apt-get with the existing system configuration.

Run Read-Only Queries

Place apt-cache or dpkg-query immediately after jf apt to invoke that binary.

To run a read-only APT query:

1. Run one of the following commands:

   Shell

   jf apt apt-cache policy <PACKAGE>
   jf apt dpkg-query -W <PACKAGE>

   Where:

   • <PACKAGE>: Debian package name to query

   For example:

   Shell

   jf apt apt-cache policy curl
   jf apt dpkg-query -W curl

These query tools use the existing system configuration. JFrog CLI doesn't create a temporary source for them.

Collect Build-Info for an APT Install

After a successful jf apt install, JFrog CLI can save dependency build-info locally when --build-name and --build-number are both set, or when you export JFROG_CLI_BUILD_NAME and JFROG_CLI_BUILD_NUMBER. Other apt-get operations, including upgrade and remove, don't collect build-info. apt-cache and dpkg-query don't collect build-info.

JFrog CLI strips the build flags before it runs apt-get. The local record uses module type debian and dependency type deb. Collection failure is logged as a warning and doesn't fail the install.

This dependency record isn't a substitute for publishing .deb files. To record Debian artifact details for a package you deploy, use jf rt upload with --deb.

To collect build-info for an APT install:

1. Run:

   Shell

   sudo jf apt install <PACKAGE> \
     --repo=<REPO_KEY> \
     --dist=<DISTRIBUTION> \
     --build-name=<BUILD_NAME> \
     --build-number=<BUILD_NUMBER>

   Where:

   • <PACKAGE>: Debian package name to install
   • <REPO_KEY>: Artifactory Debian repository key for a one-off source. Omit --repo and --dist after jf setup apt
   • <DISTRIBUTION>: Debian or Ubuntu distribution codename
   • <BUILD_NAME>: Logical build name
   • <BUILD_NUMBER>: Build number or CI ID

   For example:

   Shell

   sudo jf apt install curl \
     --repo=debian-virtual \
     --dist=bookworm \
     --trusted \
     --build-name=my-apt-build \
     --build-number=1

   After a successful install, expected output includes:

   Text

   Collecting apt build-info for my-apt-build/1 (1 package(s))

   JFrog CLI then prints apt build-info collected with the recorded dependency count and a jf rt bp my-apt-build 1 publish hint.

2. Publish the local build-info to Artifactory:

   Shell

   jf rt build-publish <BUILD_NAME> <BUILD_NUMBER>

   For example:

   Shell

   jf rt build-publish my-apt-build 1

To install packages from a list file and collect build-info:

1. Create a text file with one package per line. You can pin versions and add comments.

   Text

   # CI package list
   curl
   vim

2. Run:

   Shell

   sudo jf apt install --from-file=<PACKAGE_LIST> \
     --repo=<REPO_KEY> \
     --dist=<DISTRIBUTION> \
     --build-name=<BUILD_NAME> \
     --build-number=<BUILD_NUMBER>

   Where:

   • <PACKAGE_LIST>: Path to the package list file

   For example:

   Shell

   sudo jf apt install --from-file=packages.txt \
     --repo=debian-virtual \
     --dist=bookworm \
     --trusted \
     --build-name=my-apt-build \
     --build-number=1

Remove JFrog-Managed APT Configuration

Use --remove to delete files created by jf setup apt.

To remove JFrog-managed APT configuration:

1. Run the command that matches the files you want to delete:

   • Remove every JFrog-managed APT source, preference, and key.

     Shell

     sudo jf setup apt --remove

   • Remove configuration for one repository.

     Shell

     sudo jf setup apt --remove --repo=<REPO_KEY>

   • Remove configuration for one distribution.

     Shell

     sudo jf setup apt --remove --dist=<DISTRIBUTION>

   • Limit removal by both repository and distribution.

     Shell

     sudo jf setup apt --remove --repo=<REPO_KEY> --dist=<DISTRIBUTION>

   Where:

   • <REPO_KEY>: Artifactory Debian repository key used during setup
   • <DISTRIBUTION>: Debian or Ubuntu distribution used during setup

   For example:

   Shell

   sudo jf setup apt --remove --repo=debian-virtual --dist=bookworm

Removal is idempotent. If no matching JFrog-managed files exist, the command reports that no configuration was found.

Important Notes for APT Commands

• --repo and --dist must be passed together for one-off authentication. If only one is passed, JFrog CLI warns that the partial flag was ignored.
• A temporary source includes only the selected Artifactory repository. Use a virtual repository that can resolve transitive dependencies.
• A persistent source remains active for native apt-get commands, not only commands run through jf apt.
• Setup validates repository, distribution, and component values before using them in source lines or file paths.
• If setup can't write under /etc/apt/, run it with sufficient privileges.
• jf apt doesn't add deb-src entries.
• jf apt doesn't upload .deb files. Use jf rt upload with --deb to publish a Debian package and record artifact details.
• jf apt install collects local build-info only when both --build-name and --build-number are set. Publish that record with jf rt build-publish. A collection warning doesn't fail the install.

Troubleshooting

The following table lists common symptoms and how to resolve them.

Enable debug logging when you need command-routing details:

export JFROG_CLI_LOG_LEVEL=DEBUG

Debug output should be handled as sensitive operational data even though JFrog CLI masks known credential values.

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• Debian Repositories
• JFrog CLI Build Tool Commands
• Configure JFrog CLI
• JFrog CLI Command Reference
• Use apk with JFrog CLI