# Install Artifacts

Documentation index: https://myartifacts.dev/llms.txt
Human-readable guide: https://myartifacts.dev/install

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 each setup step in order. Check before changing anything: if `artifacts version --check --json` reports installation status `matches` and `artifacts account --profile NAME` shows the right email, you are done. Update, rollback and uninstall are optional maintenance steps.

## 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`.

```sh
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

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`.

```sh
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.

```sh
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:

```sh
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`:

```sh
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.

```sh
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).

```sh
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.