MACOS · LINUX · ANY AGENT

Install Artifacts

One command installs the artifacts CLI. Your agent uses it to read, publish and update your artifacts.

Let your agent set it up

Install the Artifacts CLI by following https://myartifacts.dev/install.md. Then sign in with the profile name I choose and confirm my account.

Prefer to follow the steps yourself? The same instructions are below. Sign-in uses a short code you approve in any browser.

1. Install

Run this in a terminal, or ask your agent to run it. It downloads the CLI for your machine, checks the download against the published SHA-256 and puts artifacts in ~/.local/bin. No Node.js and no GitHub access needed. Running it again is safe and repairs an install.

Run as a normal user, not root or sudo. In a root container, set ARTIFACTS_ALLOW_ROOT=1. The installer needs curl or wget, gzip, awk, and shasum or sha256sum.

curl -fsSL https://myartifacts.dev/install.sh | sh

Works on macOS (Apple Silicon and Intel) and Linux (x64 and arm64, glibc; x64 needs AVX2). If the installer says ~/.local/bin is not on your PATH, add the line it prints to your shell profile. Then run the printed export PATH=… line in this shell too, or call ~/.local/bin/artifacts.

2. Sign in

Ask the user which account (email) and profile name to use. Run artifacts profiles first and reuse an existing profile they pick. Never invent NAME; replace it with their chosen profile name in every command.

Run artifacts login --profile NAME and follow the code prompt: open the link it prints (https://myartifacts.dev/device) in any browser, check the code, account and device hostname shown, and approve if they match. Works over SSH and on machines without a browser. Agents: relay the link and code only to the user who asked you to sign in; never paste tokens or relay device_code.

artifacts login --profile NAME

Codes last 15 minutes; the CLI replaces an expired code at most three times. Ctrl-C preserves the previous login. Use artifacts login --profile NAME --browser for the old local-browser flow.

3. Check

Confirm the account email before doing anything else.

artifacts account --profile NAME
artifacts list --profile NAME

4. Use it

Start here: artifacts help getting-started. Every command has --help, and errors name the next command to run. To publish a folder:

artifacts publish ./folder --title "Weekly review" --profile NAME -i

Agents: start with artifacts help getting-started, then register a session and publish with its --context FILE instead of -i:

artifacts session start --agent NAME --context-file FILE --profile NAME
artifacts publish ./folder --profile NAME --context FILE

5. Your agent

Codex, Claude Code, Cursor, Devin and any terminal: same commands, run in the agent’s shell with the same profile name every time.

6. Update and roll back

Run artifacts update --check to check for a newer release. The CLI also tells you when a newer version is out.

artifacts update --check
artifacts update
artifacts update --rollback

Use --rollback only if you want to return to the previous installed version.

7. Uninstall

Remove the link and the installed versions. Your sign-ins stay in ~/.config/artifacts until you delete them. You can also remove ~/.local/state/artifacts (update-check state).

rm -f ~/.local/bin/artifacts
rm -rf ~/.local/share/artifacts/versions ~/.local/share/artifacts/install.json ~/.local/share/artifacts/install.lock

Older plugin installs also left ~/.local/share/artifacts/cli and runtime; remove them only if no plugin uses them.

8. Troubleshooting

Code expired: run artifacts login --profile NAME again.

Older plugin setup fails with 'Existing artifacts command is not owned by this installer': the standalone CLI is already installed. Skip that installer and run artifacts version --check --json.

A command from these docs is missing: run artifacts update, then retry.

install.sh prints an error: follow its message. On Linux it needs glibc (not Alpine) and, on x64, AVX2.