Authentication

Both the Python and TypeScript SDKs discover credentials automatically. This guide covers the credential resolution chain, how to override it, and how to configure the SDK for different environments.

Credential Resolution Order

The SDK checks four sources in order and uses the first credential found:

Programmatic — pass a token directly via configure() or the client constructor (takes precedence over all other sources)
MUSHER_API_KEY environment variable — the simplest option for CI pipelines and local development
OS keyring (musher/<host>) — automatically set when you run musher auth login via the CLI
Credential file (~/.local/share/musher/credentials/<host>/api-key) — file-based fallback for environments without a keyring

Environment Variable

Set the MUSHER_API_KEY environment variable before running your application:

bash

export MUSHER_API_KEY="mush_..."

This is the recommended approach for CI pipelines and server deployments.

Programmatic Configuration

Override credential discovery entirely by passing a token directly. This takes precedence over all other sources.

python

import musher

# Global configuration — affects all subsequent calls
musher.configure(token="mush_...")

# Or per-client
from musher import Client

with Client(config=musher.MusherConfig(token="mush_...")) as client:
    bundle = client.pull("acme/code-review-kit")

typescript

import { configure, MusherClient } from "@musher-dev/musher-sdk";

// Global configuration
configure({ apiKey: "mush_..." });

// Or per-client
const client = new MusherClient({ apiKey: "mush_..." });
const bundle = await client.pull("acme/code-review-kit");

SDK Configuration Options

Beyond authentication, you can configure the base URL, caching, timeouts, and verification behavior.

python

import musher

musher.configure(
    token="mush_...",              # API token
    registry_url="https://...",     # Custom registry (default: https://api.musher.dev)
    verify_checksums=True,          # SHA-256 verification on pull (default: True)
    timeout=30.0,                   # HTTP timeout in seconds (default: 30.0)
    max_retries=2,                  # Retry count for transient failures (default: 2)
)

typescript

import { configure } from "@musher-dev/musher-sdk";

configure({
  apiKey: "mush_...",              // API token
  baseUrl: "https://...",          // Custom registry (default: https://api.musher.dev)
  cacheDir: "/custom/cache",       // Custom cache directory
  manifestTtlSeconds: 86400,       // Manifest cache TTL (default: 24h)
  timeout: 60000,                  // HTTP timeout in ms (default: 60s)
  retries: 3,                      // Retry count (default: 3)
});

Python configuration fields

Field	Type	Default	Description
`token`	`str \| None`	Auto-discovered	API token (overrides credential discovery)
`registry_url`	`str`	`https://api.musher.dev`	Registry base URL
`verify_checksums`	`bool`	`True`	Verify SHA-256 checksums during pull
`timeout`	`float`	`30.0`	HTTP timeout in seconds
`max_retries`	`int`	`2`	Retry count for transient failures
`cache_dir`	`Path`	Platform default	Local cache directory for pulled bundles

TypeScript configuration fields

Field	Type	Default	Description
`apiKey`	`string`	Auto-discovered	API token (overrides credential discovery)
`baseUrl`	`string`	`"https://api.musher.dev"`	Registry base URL
`cacheDir`	`string`	Platform default	Local cache directory for pulled bundles
`manifestTtlSeconds`	`number`	`86400`	Manifest cache TTL in seconds (24 hours)
`timeout`	`number`	`60000`	HTTP timeout in milliseconds
`retries`	`number`	`3`	Retry count for transient failures

Inspect Active Configuration

python

import musher

config = musher.get_config()
print(f"Registry: {config.registry_url}")
print(f"Cache: {config.cache_dir}")
print(f"Verify: {config.verify_checksums}")

typescript

import { getClient } from "@musher-dev/musher-sdk";

// The global client reflects the active configuration
const client = getClient();