cargo-login

Add an API token to the local credential storage (located in $CARGO_HOME/credentials.toml)

$ cargo login

$ cargo login --registry [name]

cargo login [OPTIONS] [TOKEN]

cargo login --registry REGISTRY [TOKEN]

[TOKEN]
    The API token to store. If omitted, the command will prompt for it interactively via standard input.

--registry
    Specifies the name of the registry to log into. For example, '--registry my-private-registry'. If not specified, it defaults to 'crates.io'.

--help
    Prints help information about the command and exits.

The cargo login command is used to store an API token for authenticating with a Cargo registry, such as crates.io or a custom private registry. This token is essential for operations that require authentication, primarily publishing new crates (cargo publish) or managing existing ones. When executed without a token argument, cargo login will prompt the user to enter the token interactively. Alternatively, the token can be piped to standard input for non-interactive scripts.

The provided API token is stored in the ~/.cargo/credentials.toml file. By default, it stores the token for the crates.io registry. However, the --registry option allows specifying a different registry, enabling authentication with private or internal Cargo repositories. This command streamlines the authentication process, allowing developers to interact with Cargo registries without manually passing authentication headers for each command.

The API token is stored in ~/.cargo/credentials.toml. While this file's permissions are typically set to be user-readable only, the token itself is stored in plaintext. It is crucial to protect this file from unauthorized access, as the token grants publishing privileges to the associated registry. Users should ensure their tokens have appropriate scopes and revoke them if compromised or no longer needed.

The API token is stored in the ~/.cargo/credentials.toml file. This file uses TOML format and typically contains a section for each registry with its corresponding token.

Before logging into a custom registry, it must be defined in your ~/.cargo/config.toml file. For example:
[registries.my-private-registry]
index = "https://my-private-registry.com/git/index"
After configuration, you can use cargo login --registry my-private-registry.

As an alternative to storing the token via cargo login, you can provide a token using an environment variable. For example, for the crates.io registry, set CARGO_REGISTRIES_CRATES_IO_TOKEN=your_token_here. For a custom registry named my-private-registry, use CARGO_REGISTRIES_MY_PRIVATE_REGISTRY_TOKEN=your_token_here. This is useful for CI/CD environments or temporary authentication.

The cargo login command has been a fundamental part of the Cargo build system and package manager since its early development. It was introduced to provide a standardized and user-friendly method for authenticating with crates.io and custom registries, a necessity for the package distribution model of the Rust ecosystem. Its inclusion significantly simplified the workflow for publishing and managing Rust crates, making secure registry interactions accessible to developers.

cargo publish(1), cargo owner(1), cargo config(1), cargo(1)