o41-artifacts

Command line tool for 041 Artifacts: versioned file sets in your own buckets. It does everything the app does: sign-in, cloud connections, locations, API keys, listing, reading, writing, and usage.

Install

curl -fsSL https://artifacts.041.io/install.sh | sh

The installer verifies SHA-256 and installs o41-artifacts in ~/.local/bin for Linux and macOS on x64 and arm64. It needs no Node.js or npm. Set O41_ARTIFACTS_INSTALL_DIR to choose another directory, and put it first on PATH. If you installed with npm, remove that copy with npm uninstall -g @o41/artifacts so it does not hide the standalone binary.

Updates

o41-artifacts update --check
o41-artifacts update

Standalone installations check for updates in the background at most once every six hours. A verified download replaces the binary atomically for later commands; running commands continue with their current version. Network failures leave the installed binary in place and do not change command output or exit status. Set O41_AUTO_UPDATE=0 to disable automatic updates for all 041 CLIs, or O41_ARTIFACTS_AUTO_UPDATE=0 for this CLI. CI and npm installations skip automatic updates. Explicit update still works when automatic updates are disabled.

Sign in

o41-artifacts login            # browser sign-in on any device; picks your org if you have one
o41-artifacts org list         # your organizations, * marks the active one
o41-artifacts org use my-org   # id, slug, or name
o41-artifacts whoami
o41-artifacts logout

Boxes and scripts use an organization API key instead:

export O41_ARTIFACTS_API_KEY=ak_...

O41_ARTIFACTS_TOKEN with O41_ARTIFACTS_ORG sends a raw bearer token for an organization. The CLI talks to https://artifacts.041.io unless --url or O41_ARTIFACTS_URL names another origin. Sign-ins are saved per origin in ~/.config/o41-artifacts/auth.json.

Set up an organization

o41-artifacts org                                   # connections, locations, ready for writes?
o41-artifacts connections create --cloud gcp --name prod
o41-artifacts connections complete <id> projectId=... projectNumber=... poolId=... providerId=... serviceAccountEmail=...
o41-artifacts locations create --connection <id> --region europe-west4 --fallback
o41-artifacts locations add-s3 --endpoint https://fly.storage.tigris.dev --bucket b \
  --access-key-id tid_... --secret-stdin --cloud tigris --region global < secret.txt
o41-artifacts locations set <id> --default
o41-artifacts api-keys create ci
o41-artifacts usage --days 7

Read and write

o41-artifacts ls experiments/
o41-artifacts versions experiments/run-1
o41-artifacts show experiments/run-1               # latest
o41-artifacts url o41://experiments/run-1/latest params.safetensors
o41-artifacts get o41://experiments/run-1/latest ./ckpt
o41-artifacts put experiments/run-1 step-00000600 params.safetensors state.json --meta '{"step": 600}'

put opens the artifact's writer from the latest version, so a run still writing there is fenced off. Version names only ascend. Placement uses O41_ARTIFACTS_CLOUD and O41_ARTIFACTS_REGION when both are set, else the organization's fallback.

Every command takes --json for machine output; errors go to stderr with exit code 1.

Docs search

Find the docs pages that answer a question. Each hit prints the page's title, its markdown URL and the passage that matched. It needs no sign-in.

o41-artifacts docs search "resume a run after preemption"
o41-artifacts docs search api keys --limit 10 --json

Feedback

Report a bug or an idea to the 041 team. It needs no sign-in and attaches the CLI and Bun versions, the OS and its version, the URL and the sign-in identity (never a key); no working directory, file or environment variable.

o41-artifacts feedback --bug "get stalls at 99% on a cross-cloud read"
o41-artifacts feedback --reply-to [email protected] "a dry-run flag for put"
o41-artifacts feedback --bug - < report.md

Usage analytics

After each command the CLI sends one usage report to the deployment it talks to: the command path, such as o41-artifacts put, never an argument or a value, with its outcome, duration, the CLI version and the platform. It counts for the organization of the credential the command uses. It waits at most 1.5 seconds and never changes a command's result. O41_ARTIFACTS_ANALYTICS=off or DO_NOT_TRACK=1 turns it off. The CLI docs list every field.

Development

bun run --filter @o41/artifacts dev --help
bun run --filter @o41/artifacts test
bun run --filter @o41/artifacts lint
bun run --filter @o41/artifacts build