Use Cargo with JFrog CLI

Run Cargo, the Rust package manager, with JFrog Artifactory integration for registry configuration, credential injection on selected subcommands, and optional build-info collection.

This topic covers the following tasks:

• Configure Cargo for Artifactory
• Run Cargo Commands
• Publish Crates
• Run Native Cargo Subcommands

When to Use

Use jf cargo for Rust projects that use Cargo when Cargo.toml is in the project or workspace root. JFrog CLI wraps the local cargo binary, injects Artifactory credentials for build, install, and publish, and can record build-info.

• Run jf setup cargo once per environment to write the jfrog and optional jfrog-local registries into Cargo's user-level config.
• Run jf cargo build or jf cargo install with --build-name and --build-number to collect dependency build-info locally.
• Run jf cargo publish with those flags to collect dependency and .crate artifact build-info locally, then publish the record with jf rt build-publish.
• Run other native Cargo subcommands through jf cargo as a passthrough with no build-info.

If you don't need build-info or JFrog-managed credentials, you can point Cargo at Artifactory yourself. For more information, see Cargo Repositories.

Prerequisites

• Cargo on PATH: jf cargo doesn't install Rust. Verify with cargo --version. Install from rustup if the binary is missing.
• 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 Cargo repositories: Create a remote Cargo repository for resolution as a crates.io proxy. Create a local Cargo repository if you publish crates. Artifactory doesn't provide virtual Cargo repositories. For more information, see Cargo Repositories.
• Write access to Cargo home for setup: jf setup cargo writes $CARGO_HOME/config.toml and, when credentials exist, $CARGO_HOME/credentials.toml. The default $CARGO_HOME is ~/.cargo.
• JFROG_HOME (optional): Set this variable if you use a non-default directory for JFrog CLI configuration files.

Configure Cargo for Artifactory

jf setup cargo configures the local Cargo client to resolve crates through an Artifactory remote repository that replaces crates.io. You can also configure it to publish to an Artifactory local repository.

There's no jf cargo-config or jf cargo config command. Use jf setup cargo.

To configure Cargo for Artifactory:

1. Configure a JFrog CLI server with jf c add or jf config add.
2. Run jf setup cargo --server-id=<server-id> --repo=<remote-repository-key> for resolution-only setup, or omit --repo to select a remote repository and optionally a local publish repository interactively.
3. Confirm $CARGO_HOME/config.toml contains [registries.jfrog] with a sparse+https://<host>/artifactory/api/cargo/<repo>/index/ URL.

Synopsis

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

Where:

• <server-id>: JFrog CLI server ID from jf config add.
• <repository-key>: Artifactory remote Cargo repository key used for resolution.
• <project-key>: JFrog project key used when listing repositories interactively.

Options

The following options apply to jf setup cargo.

Setup writes the following files.

• $CARGO_HOME/config.toml: [registry] default = "jfrog", [registries.jfrog] index, [source.crates-io] replace-with = "jfrog", and global-credential-providers = ["cargo:token"]. If you selected a local repository interactively, the file also includes [registries.jfrog-local].
• $CARGO_HOME/credentials.toml: [registries.jfrog] token as Bearer <access-token> or Basic <base64(user:password)>, matching the configured server. File mode is 0600.

After setup, native cargo build resolves through Artifactory. Publish with cargo publish --registry jfrog-local or jf cargo publish --registry jfrog-local.

Configure Cargo with Flags

To run non-interactive setup:

1. Run:

jf setup cargo --server-id=my-server --repo=cargo-remote

Expected result: Successfully configured cargo to use JFrog repository 'cargo-remote'.

Run Cargo Commands

jf cargo runs the cargo binary with stdin, stdout, and stderr passed through. JFrog CLI removes its own options (--build-name, --build-number, --module, --project, --server-id) from the argument list wherever they appear, then passes the remaining tokens to cargo in order.

When --build-name and --build-number are both set, or when you supply JFROG_CLI_BUILD_NAME and JFROG_CLI_BUILD_NUMBER, and the Cargo subcommand is build or install, the CLI collects build-info after a successful run and prints cargo build info saved locally. Publish that record later with jf rt build-publish.

For build, install, and publish, the CLI injects CARGO_REGISTRIES_<NAME>_TOKEN and enables cargo:token for every registry in Cargo config whose index URL is on the same Artifactory host and path as the selected server. Other subcommands don't receive this injection. They use credentials already in Cargo, for example from jf setup cargo.

Synopsis

jf cargo [jfrog-options ...] <cargo-subcommand> [cargo-args ...]

Where:

• <cargo-subcommand>: First token passed to cargo after JFrog-specific options are removed.
• [cargo-args ...]: Remaining arguments and flags forwarded to cargo.

JFrog options are --build-name, --build-number, --module, --project, and --server-id. They can appear before or after the Cargo subcommand.

Aliases: none.

Arguments

The following argument is required.

Build Options

The following flags apply to build-info and credential injection.

Record Build-Info for a Cargo Build

To record build-info for a Cargo build:

1. From the crate or workspace directory, run:

jf cargo build --build-name=<build-name> --build-number=<build-number>

Where:

• <build-name>: Logical build name. For example, docs-cargo.
• <build-number>: Build number or CI ID. For example, 1.

Full example:

jf cargo build --build-name=docs-cargo --build-number=1

Cargo prints its usual compile lines first. Those lines vary by crate, profile, and machine. After a successful run, JFrog CLI prints:

[Info] cargo build info saved locally

The local record includes a module with "type": "cargo" and "id": "<crate-name>:<version>".

Collect Build-Info from Environment Variables

To collect build-info using environment variables:

1. Set JFROG_CLI_BUILD_NAME and JFROG_CLI_BUILD_NUMBER, then run jf cargo build:

export JFROG_CLI_BUILD_NAME=ci-cargo-env
export JFROG_CLI_BUILD_NUMBER=99
jf cargo build

Expected output includes [Info] cargo build info saved locally. The saved record uses name ci-cargo-env and number 99.

Publish Crates

jf cargo publish runs native cargo publish with your Cargo arguments, for example --registry jfrog-local or -p <crate>. On success, if --build-name and --build-number are both set, the CLI collects dependency build-info and the published .crate artifact from target/package. If Cargo deleted the local file, the CLI collects the artifact from Artifactory with Artifactory Query Language (AQL). Then it saves the record locally.

To publish a crate and collect build-info:

1. Run jf setup cargo so the jfrog-local registry exists, or pass --registry for a registry already in .cargo/config.toml.
2. Run:

jf cargo publish --registry jfrog-local --build-name=<build-name> --build-number=<build-number>

Where:

• <build-name>: Logical build name. For example, docs-cargo.
• <build-number>: Build number or CI ID. For example, 1.

3. Publish the local build-info to Artifactory:

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

Full example:

jf cargo publish --registry jfrog-local --build-name=docs-cargo --build-number=1
jf rt build-publish docs-cargo 1

Run Native Cargo Subcommands

Subcommands other than build, install, and publish are forwarded to cargo with no build-info collection and no per-run token injection. Examples include test, check, add, and metadata.

To run Cargo tests through JFrog CLI:

1. From the crate or workspace directory, run:

jf cargo test

The command prints native cargo test output. JFrog CLI doesn't print cargo build info saved locally.

To run Cargo check through JFrog CLI:

1. From the crate or workspace directory, run:

jf cargo check

The command prints native cargo check output. JFrog CLI doesn't print cargo build info saved locally.

Important Notes

• jf cargo requires at least one Cargo argument. jf cargo with no subcommand prints usage and exits 1 with Wrong number of arguments (0).
• jf cargo doesn't parse or rewrite Cargo flags except the JFrog flags listed above. Native flags such as --release, --features, -p, and --manifest-path go to cargo. Feature and --manifest-path flags that cargo metadata understands are also used when collecting build-info.
• Workspace members: -p or --package limits which members appear as build-info modules.
• jf cargo doesn't upload build-info. Use jf rt build-publish.
• Token values aren't printed in normal logs. Debug logs redact cargo login tokens and --token values.

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

• Cargo Repositories
• Build Tools
• Binary Management with Artifactory
• Use apk with JFrog CLI