Use APM with JFrog CLI

Run Agent Package Manager (APM) with JFrog Artifactory integration for registry configuration, per-run credential injection, and optional build-info collection.

This topic covers the following tasks:

• Configure APM for Artifactory
• Install Agent Packages
• Publish Agent Packages
• Run Native APM Subcommands

When to Use

Use jf agent apm when you manage Agent Packages with the native apm CLI and want JFrog CLI to authenticate against Artifactory and, for install and publish, to record build-info.

• Run jf setup apm once per environment to write the Artifactory registry into ~/.apm/config.json.
• Run jf agent apm install or jf agent apm publish with --build-name and --build-number to collect build-info locally, then publish the record with jf rt build-publish.
• Run other native APM subcommands through jf agent apm as a passthrough with authenticated registry access and no build-info.

If you only need native APM configuration without JFrog CLI, you can set registry URL and token yourself. For more information, see Agent Packages Repositories.

Prerequisites

• APM on PATH: jf agent apm and jf setup apm don't install APM. JFrog CLI requires APM 0.23.0 or later. Install from the Agent Package Manager documentation.
• JFrog CLI installed and authenticated: Install or upgrade from the JFrog CLI quick start, then configure a server with jf config add or jf c add. Use --server-id when you need a server other than the default.
• Artifactory Agent Packages repository: Create a local Agent Packages repository. Artifactory doesn't provide remote or virtual Agent Packages repositories for APM install and publish. For more information, see Agent Packages Repositories.
• Write access to APM user config for setup: jf setup apm updates ~/.apm/config.json through the native apm client.
• JFROG_HOME (optional): Set this variable if you use a non-default directory for JFrog CLI configuration files.

Configure APM for Artifactory

jf setup apm configures the local APM client to use an Artifactory local Agent Packages repository as a named registry (and as the default registry).

There's no jf apm-config command. Use jf setup apm.

To configure APM for Artifactory:

1. Configure a JFrog CLI server with jf c add or jf config add.
2. Run jf setup apm --server-id=<server-id> --repo=<local-repository-key> for non-interactive setup, or omit --repo to select a local Agent Packages repository interactively.
3. Confirm ~/.apm/config.json contains a registry named after the repository key, with URL https://<host>/artifactory/api/agentpackages/<repo>/ and a token.

After setup, native apm install and apm publish can use the same registry without going through JFrog CLI.

Synopsis

jf setup apm [--server-id=<server-id>] [--repo=<repository-key>] [--project=<project-key>]

Where:

• <server-id>: JFrog CLI server ID from jf config add.
• <repository-key>: Artifactory local Agent Packages repository key.
• <project-key>: JFrog project key used when listing repositories interactively.

Options

The following options apply to jf setup apm.

Setup runs native APM config commands that enable registries and set registry.<repository-key>.url, registry.<repository-key>.token, and registry.<repository-key>.default to true. Re-running setup for a different repository makes that repository the default.

Configure APM with Flags

To run non-interactive setup:

1. Run:

jf setup apm --server-id=my-server --repo=agent-packages-local

Expected result includes: Successfully configured apm to use JFrog repository 'agent-packages-local'.

Install Agent Packages

jf agent apm install runs native apm install with Artifactory credentials injected for the current process only. Those credentials aren't written to disk. Remaining arguments and native flags (--frozen, --dev, --root, --dry-run, --target, positional owner/name#version) go to apm.

When --build-name and --build-number are both set, or when you supply JFROG_CLI_BUILD_NAME and JFROG_CLI_BUILD_NUMBER, and the install isn't --dry-run, the CLI collects dependency build-info from apm.lock.yaml after a successful run (registry-sourced dependencies only). If the project has no dependencies, APM doesn't write a lockfile and build-info is skipped.

--root redirects apm_modules/ and apm.lock.yaml. Build-info collection reads the lockfile from that directory. apm.yml still resolves from the current working directory.

Synopsis

jf agent apm install [jfrog-options ...] [apm-install-args ...]

JFrog options are --build-name, --build-number, --module, --project, and --server-id. They can appear before or after native APM flags. JFrog CLI removes them before invoking apm.

Build Options

The following flags apply to build-info and server selection for install and publish.

To install dependencies from apm.yml and record build-info:

1. From the directory that contains apm.yml, run:

jf agent apm install --build-name=<build-name> --build-number=<build-number>

Full example:

jf agent apm install --build-name=docs-apm --build-number=1

After a successful run, JFrog CLI prints apm install finished successfully. When build-info is collected, it also prints Collecting APM build info... and APM build info saved for <build-name>/<build-number>: <n> dependencies.

To install a package on the command line:

jf agent apm install my-org/my-package#1.0.0 --target claude

A bare #1.0.0 pin is exact. Use a range such as #^1.0.0 if later installs should pick up newer matching versions.

To preview an install without changing files or recording build-info:

jf agent apm install --dry-run

Publish Agent Packages

jf agent apm publish runs native apm publish. --package <owner>/<name> is required. JFrog CLI doesn't infer the package from a positional argument.

If more than one registry is configured in ~/.apm/config.json, pass native --registry <repository-key> so APM doesn't refuse to guess the target.

On success, if --build-name and --build-number are both set and the command isn't --dry-run, the CLI records the published .zip artifact in local build-info. --zip sets the archive path whose checksum is recorded.

To publish a package and collect build-info:

1. Run jf setup apm (or declare a matching registries: block in apm.yml).
2. Run:

jf agent apm publish --package=<owner>/<name> --registry=<repository-key> --build-name=<build-name> --build-number=<build-number>

3. Publish the local build-info to Artifactory:

jf rt build-publish <build-name> <build-number>

Full example:

jf agent apm publish --package=frog/my-package --registry=agent-packages-local --build-name=docs-apm --build-number=1
jf rt build-publish docs-apm 1

Without --package, the command fails with: jf agent apm publish requires --package <owner>/<name>, e.g. --package acme/my-skill

--dry-run packs locally but uploads nothing and skips build-info.

Run Native APM Subcommands

Subcommands other than install and publish are forwarded to apm with credential injection and no build-info collection. Examples include lock, outdated, audit, view, and marketplace.

jf agent apm with no subcommand prints native apm help.

To run APM lock through JFrog CLI:

jf agent apm lock

To run a passthrough command against a named JFrog CLI server:

jf agent apm outdated --server-id=my-server

--server-id is consumed by JFrog CLI and is not passed to apm. For native APM help, run jf agent apm <subcommand> --help or apm --help.

Important Notes

• jf agent apm doesn't upload build-info. Use jf rt build-publish.
• install and publish collect build-info only when both build name and build number are set.
• Build-info modules use type apm.
• jf agent apm doesn't accept --repo. Configure the registry with jf setup apm or apm.yml registries:.
• Token values aren't written during install or publish. Setup is the path that persists a token in ~/.apm/config.json.

Troubleshooting

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

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• Agent Packages Repositories
• JFrog CLI for Skills
• JFrog CLI for Agent Plugins
• Build Tools
• Binary Management with Artifactory