Use Chocolatey with JFrog CLI

Run Chocolatey through JFrog CLI against a JFrog Artifactory NuGet repository. jf choco forwards arguments to the native choco client and can record build-info for install, upgrade, pack, and push.

This topic covers the following tasks:

Configure Chocolatey for Artifactory
Install or Upgrade from a Configured Source
Install with Repo Resolve
Pack and Push

When to Use

Use jf choco on Windows when Chocolatey packages are stored in an Artifactory NuGet repository. JFrog CLI 2.126.0 and later include jf setup choco and jf choco.

Run jf setup choco once on the machine to add an authenticated Chocolatey source.
Run jf choco install or jf choco upgrade to resolve packages. Pass --build-name and --build-number to record dependencies.
Run jf choco pack and jf choco push with those flags to record the packages you produce, then publish the record with jf rt build-publish.
Other native Chocolatey subcommands run through jf choco as a passthrough and don't collect build-info.

jf choco always runs the native Chocolatey client. There's no jf choco-config command and no Wrapped Mode. You don't set JFROG_RUN_NATIVE.

Chocolatey uses a NuGet repository. Artifactory doesn't have a separate Chocolatey package type. For native choco source commands without JFrog CLI, see NuGet Repositories: Chocolatey Client.

📘
Note
Package Alias doesn't intercept choco. Run jf choco, or run native choco after jf setup choco. For more information, see Use JFrog CLI Package Alias.

Prerequisites

JFrog CLI 2.126.0 or later. Verify with jf --version.
Windows. jf setup choco and jf choco fail on other operating systems.
Chocolatey installed and available as choco. Verify with choco --version.
An elevated shell for jf setup choco. Setup writes the machine-wide Chocolatey configuration.
A JFrog CLI server configured with jf config add. Chocolatey authenticates with HTTP basic authentication, so the server configuration needs a username and a password or access token. A reference token that has no username can't be stored on the Chocolatey source. Re-run jf config add with a username, or use a JSON Web Token access token.
An Artifactory NuGet repository, virtual, local, or remote, that your account can read. Push also needs write permission on a local repository, or on a virtual repository that deploys to a local NuGet repository.

🚧
Warning
If the Artifactory URL uses http:// and the host isn't loopback, jf setup choco still writes the source and warns that the stored credentials and API key are sent unencrypted. Use HTTPS for Artifactory.

Configure Chocolatey for Artifactory

jf setup choco adds one named Chocolatey source for an Artifactory NuGet repository and stores the API key used for push. The source name is jfrt-<hostname>-<repository-key>, with characters outside letters, digits, ., _, and - replaced by -.

Setup uses the NuGet V2 feed. Chocolatey reads and pushes through that V2 endpoint.

To configure Chocolatey:

Open an elevated Windows shell.
Run jf setup choco. Select a NuGet virtual, local, or remote repository, or pass --repo for a non-interactive run.
```
jf setup choco --server-id=<SERVER_ID> --repo=<REPOSITORY_KEY> --project=<PROJECT_KEY>
```
Where:
- <SERVER_ID>: JFrog CLI server ID from jf config add. Omit --server-id to use the default server.
- <REPOSITORY_KEY>: NuGet repository key. Omit --repo to choose the repository type and repository interactively.
- <PROJECT_KEY>: JFrog Project key, when the repository belongs to a project. Omit --project when the repository isn't in a project.
For example:
```
jf setup choco --server-id=my-server --repo=nuget-virtual
```
On success, the command prints the source name:
```
Chocolatey source name: jfrt-acme.jfrog.io-nuget-virtual
```
Use that name as the native -s value on later jf choco commands.

📘
Note
JFrog CLI adds virtual and remote repositories with --priority=1. JFrog CLI adds a local repository without that priority. Re-running setup for the same repository refreshes that source's URL and credentials and leaves other Chocolatey sources in place. The change is machine-wide. jf choco itself doesn't write Chocolatey configuration.

Run Chocolatey Commands

JFrog CLI removes its own options and forwards the rest to choco.

You can also pass the following options.

Option	Description
`--build-name`	Build name. Required with `--build-number` when you collect build-info.
`--build-number`	Build number. Required with `--build-name`.
`--module`	Module name inside the build-info. Requires both build flags.
`--project`	JFrog Project key stored on the build-info.
`--server-id`	Server ID used to build the Artifactory source URL and credentials.
`--repo-resolve`	NuGet repository used for `install` and `upgrade` when you don't pass a native source. JFrog CLI adds `-s`, and credentials when they're configured.
`--repo`	NuGet repository used for `push` build-info and, when you don't pass native push authentication, for the injected source and API key.

Install or Upgrade from a Configured Source

After jf setup choco, pass the source name with the native -s option.

To install or upgrade from a configured source:

Run jf choco install or jf choco upgrade.
```
jf choco install <PACKAGE_NAME> -s=<SOURCE_NAME> --build-name=<BUILD_NAME> --build-number=<BUILD_NUMBER>
```
Where:
- <PACKAGE_NAME>: Chocolatey package ID.
- <SOURCE_NAME>: Source name printed by jf setup choco.
- <BUILD_NAME>: Build name. Required with <BUILD_NUMBER>.
- <BUILD_NUMBER>: Build number. Required with <BUILD_NAME>.
For example:
```
jf choco install git -s=jfrt-acme.jfrog.io-nuget-virtual --build-name=image --build-number=1
```

Install with Repo Resolve

--repo-resolve points that command at the repository without using a previously registered source.

To install with --repo-resolve:

Run jf choco install or jf choco upgrade. Don't also pass a native -s, -u, or -p if you want JFrog CLI to inject the source.
```
jf choco install <PACKAGE_NAME> --repo-resolve=<REPOSITORY_KEY> --server-id=<SERVER_ID> --build-name=<BUILD_NAME> --build-number=<BUILD_NUMBER>
```
Where:
- <PACKAGE_NAME>: Chocolatey package ID.
- <REPOSITORY_KEY>: Artifactory NuGet repository key.
- <SERVER_ID>: JFrog CLI server ID. Omit --server-id to use the default server.
- <BUILD_NAME>: Build name. Required with <BUILD_NUMBER>.
- <BUILD_NUMBER>: Build number. Required with <BUILD_NAME>.
For example:
```
jf choco install git --repo-resolve=nuget-virtual --server-id=my-server --build-name=image --build-number=1
```

Pack and Push

Pack records the .nupkg files that the command creates. Push records the package you upload.

To pack and push a package:

Pack the package.
```
jf choco pack --build-name=<BUILD_NAME> --build-number=<BUILD_NUMBER>
```
Where:
- <BUILD_NAME>: Build name. Required with <BUILD_NUMBER>.
- <BUILD_NUMBER>: Build number. Required with <BUILD_NAME>.
For example:
```
jf choco pack --build-name=tool --build-number=1
```
Push the package. The native -s source and --repo must identify the same Artifactory repository. When --repo is set and you don't pass native -s and -k, JFrog CLI adds them for that command.
```
jf choco push <PACKAGE_FILE> -s=<SOURCE_NAME> --repo=<REPOSITORY_KEY> --build-name=<BUILD_NAME> --build-number=<BUILD_NUMBER>
```
Where:
- <PACKAGE_FILE>: .nupkg file to push.
- <SOURCE_NAME>: Source name printed by jf setup choco for that repository.
- <REPOSITORY_KEY>: Artifactory NuGet repository key. This must be the repository that <SOURCE_NAME> pushes to.
- <BUILD_NAME>: Build name. Required with <BUILD_NUMBER>.
- <BUILD_NUMBER>: Build number. Required with <BUILD_NAME>.
For example:
```
jf choco push tool.1.0.0.nupkg -s=jfrt-acme.jfrog.io-nuget-local --repo=nuget-local --build-name=tool --build-number=1
```

Publish the collected build-info.

jf rt build-publish <BUILD_NAME> <BUILD_NUMBER>

For example:

jf rt build-publish tool 1

Chocolatey Build-Info

JFrog CLI collects build-info only when you set both --build-name and --build-number. If you pass only one of them, JFrog CLI returns an error and doesn't run the native command. The following table describes what each subcommand records.

Subcommand	Build-info
`install`, `upgrade`	Requested packages and dependencies found in Chocolatey's lib directory
`pack`	`.nupkg` files created by that pack, including files written to `--output-directory`
`push`	The pushed package, stamped against the deployment repository
Other subcommands	No build-info

🚧
Warning
JFrog CLI doesn't record a dependency served by a Chocolatey special source (ruby, cygwin, python, or windowsfeatures). JFrog CLI reports it as not found and leaves it out of the build-info. JFrog CLI records dependency build-info only for packages Chocolatey writes under its lib directory.

🚧
Warning
Chocolatey mishandles its default timeout of 2700 seconds and turns it into a 5-hour timeout. A hung install then stalls the build. Pass --execution-timeout=2700 on jf choco install and jf choco upgrade in continuous integration (CI).

Troubleshooting

The following table lists common symptoms and fixes.

Symptom	Cause	Fix
`'jf choco' requires Chocolatey, which runs on Windows only`	The command ran on macOS or Linux	Run Chocolatey on Windows
`failed to add the Artifactory source` or the API-key step fails	`choco` is missing, or the shell isn't elevated	Install Chocolatey and rerun `jf setup choco` as Administrator
`a username is required to configure Chocolatey`	The access token has no username	Re-run `jf config add` with a username, or use a JWT access token
HTTP 401 on `choco install` after a successful push	The source has an API key but no source user and password	Rerun `jf setup choco` so the source stores both the read credentials and the API key
Push build-info doesn't match the uploaded package	Native `-s` and `--repo` point at different repositories	Use the source created for that repository, and pass the same repository key to `--repo`
Install hangs for hours in CI	Chocolatey's default execution timeout	Pass `--execution-timeout=2700`

To enable debug logging, run export JFROG_CLI_LOG_LEVEL=DEBUG in the elevated shell, then rerun the command. On Windows PowerShell, use $env:JFROG_CLI_LOG_LEVEL = "DEBUG".

Frequently Asked Questions

This section provides answers to frequently asked questions about Chocolatey and JFrog CLI.

plusFAQs

Q: When do I set JFROG_RUN_NATIVE for jf choco?

A: No. jf choco always runs native Chocolatey. Configure the machine with jf setup choco, or pass --repo-resolve or --repo on the command. For more information, see Configure Chocolatey for Artifactory.

Q: Which Artifactory repository type does Chocolatey use?

A: A NuGet repository. jf setup choco accepts a NuGet virtual, local, or remote repository and registers the NuGet V2 feed.

Q: Does jf choco replace jf nuget?

A: No. Use jf nuget and jf dotnet for NuGet and .NET SDK projects. Use jf choco for Chocolatey packages on Windows.

When to Use

Prerequisites

Configure Chocolatey for Artifactory

Run Chocolatey Commands

Install or Upgrade from a Configured Source

Install with Repo Resolve

Pack and Push

Chocolatey Build-Info

Troubleshooting

Frequently Asked Questions

Q: When do I set JFROG_RUN_NATIVE for jf choco?

Q: Which Artifactory repository type does Chocolatey use?

Q: Does jf choco replace jf nuget?

Related Topics