# Python and Rust packages

Install the `packages` feature through the same installer used for the rest of
your environment:

```sh
curl -fsSL https://dotfiles.bolte.sh/install.sh -o /tmp/bolte-install.sh
sh /tmp/bolte-install.sh --features packages --yes --no-input
export PATH="$HOME/.local/bin:$PATH"
bolte-packages status
```

Feature selection is exact: include your other desired features, such as
`--features shell,git,packages`, when configuring a personal machine. The
packages feature adds `bolte-packages` and credential-free reference files under
`~/.bolte/packages`. It leaves global pip, uv, Cargo and Twine configuration
intact. It does not install those package managers or request credentials.

| Manager | Read endpoint | Publish endpoint |
| --- | --- | --- |
| pip / uv / Twine | `https://artifacts.bolte.sh/pypi/simple/` | `https://artifacts.bolte.sh/pypi/` |
| Cargo | `sparse+https://artifacts.bolte.sh/crates/` | API advertised by that index |

These are the AWS CodeArtifact Python and Cargo repositories. There is no npm
registry configured. The repositories use public PyPI and crates.io as upstreams;
the Python wrapper selects Bolte as its default index instead of combining
private and public candidates with pip's `--extra-index-url`.

Use the `bolte-` prefix for new private Python packages and Rust crates. The
infrastructure prevents public ingestion for that namespace and the existing
Python `logan` and `ax` packages. Other private names need a matching protected
package-group rule before publication; ordinary public dependencies continue
through the public upstreams. Direct publication into unregistered public
namespaces is blocked, so an API key cannot replace a public dependency.

## Credentials

`bolte-packages` reads `BOLTE_API_KEY` first, then the existing top-level
`api_key` in `~/.bolte/credentials`. The local file must belong to you and have
private permissions (`chmod 600 ~/.bolte/credentials`). It is the same TOML
credential used by the Bolte CLI; the installer never reads, copies or backs it
up. A non-default private directory can be selected with `BOLTE_HOME`.

Create or revoke API keys at [Account](https://auth.bolte.sh/account). Current
keys grant both package reading and publishing: the service does not yet issue
separately scoped read-only package keys. GitHub tokens and AWS OIDC tokens are
not accepted as Bolte API keys. Downstream users do not need AWS credentials.

For a temporary local session, enter the key without putting it in shell history:

```bash
read -rsp 'Bolte API key: ' BOLTE_API_KEY; echo
export BOLTE_API_KEY
```

The helper supplies authentication only in the selected child's environment:
pip receives an authenticated index URL; uv receives named-index and publishing
credentials; Twine receives `TWINE_PASSWORD`; Cargo receives
`CARGO_REGISTRIES_BOLTE_TOKEN` with `cargo:token`. It writes no credentials to
configuration, lockfiles or command arguments, and redacts the key from streamed
manager output. Do not add credentials to the reference configuration files.

## Local commands

Use Python 3.9+, uv 0.9.8 or newer for the examples below, and a recent Cargo
supporting authenticated sparse registries. Install pip or Twine into your
chosen Python environment when using those interfaces.

```sh
bolte-packages pip install logan
bolte-packages pip install -r requirements.txt
bolte-packages uv pip install logan
bolte-packages uv sync
bolte-packages uv sync --locked

uv build
bolte-packages uv publish dist/*
# Alternative Python uploader:
bolte-packages twine upload dist/*

bolte-packages cargo add bolte-config --registry bolte
bolte-packages cargo check
bolte-packages cargo publish --registry bolte
```

Cargo dependencies from this repository should specify `registry = "bolte"`
in `Cargo.toml`. The wrapper registers that name for resolving dependencies and
sets it as the default publishing registry; ordinary crates.io dependencies
retain their normal meaning. The credentials are never saved with `cargo login`.

uv keeps project/workspace settings, editable sources and unrelated user options
active. Its named default index is `bolte`. A project explicitly pinning a
dependency with `tool.uv.sources` must also define the matching named index in
its own `pyproject.toml`, as required by uv. The installed `uv.toml` provides a
credential-free template. Existing lockfiles naming a different registry must be
intentionally updated with `bolte-packages uv lock` before using `--locked`.

The wrapper rejects registry URL and credential overrides; use the ordinary
manager command to work with another service. Publishing always remains an
explicit command. Status and help do not read the credentials or contact AWS.

## GitHub Actions

Add a repository or protected environment secret named `BOLTE_API_KEY`, then use
the published installer without interactive prompts. This example is for a
downstream Python project with `pyproject.toml` and a committed `uv.lock`:

```yaml
name: Python packages
on: workflow_dispatch
permissions:
  contents: read

jobs:
  package:
    runs-on: ubuntu-latest
    environment: package-publishing
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - uses: astral-sh/setup-uv@v6
        with:
          version: '0.9.8'
      - name: Install package access
        run: |
          curl -fsSL https://dotfiles.bolte.sh/install.sh -o "$RUNNER_TEMP/bolte-install.sh"
          sh "$RUNNER_TEMP/bolte-install.sh" --features packages --yes --no-input
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Resolve dependencies
        env:
          BOLTE_API_KEY: ${{ secrets.BOLTE_API_KEY }}
        run: bolte-packages uv sync --locked
      - name: Build distributions
        run: uv build
      - name: Publish distributions
        env:
          BOLTE_API_KEY: ${{ secrets.BOLTE_API_KEY }}
        run: bolte-packages uv publish dist/*
```

For a Cargo project, use the same installer step and provide the same secret to
`bolte-packages cargo check --locked` and the explicit
`bolte-packages cargo publish --registry bolte` step after installing your
project's Rust toolchain. Cache dependency/build directories, not
`~/.bolte/credentials` or the job environment. No key is embedded in the
installer download, generated files or workflow YAML.

Implementation references: [uv indexes and credential environment variables](https://docs.astral.sh/uv/concepts/indexes/),
[pip authentication](https://pip.pypa.io/en/stable/topics/authentication/), and
[Cargo registry authentication](https://doc.rust-lang.org/cargo/reference/registry-authentication.html).