> ## Documentation Index
> Fetch the complete documentation index at: https://artifacts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every command, flag, environment variable, and output behavior for the artifacts CLI.

A complete reference for the `artifacts` command. New to the CLI? Start with the [CLI guide](/surfaces/cli) for setup, auth, and output behavior.

<Info>
  Each command maps directly to a REST endpoint. Run `artifacts schema` for the machine-readable version of this page.
</Info>

## Global Flags

| Flag                    | Env                          | Purpose                                           |
| ----------------------- | ---------------------------- | ------------------------------------------------- |
| `--base-url <url>`      | `AGENT_ARTIFACTS_BASE_URL`   | API base URL                                      |
| `--web-url <url>`       | `AGENT_ARTIFACTS_WEB_URL`    | Web app URL for browser login                     |
| `--token <token>`       | `AGENT_ARTIFACTS_TOKEN`      | Bearer token                                      |
| `--token-stdin`         |                              | Read bearer token from stdin                      |
| `--format <json\|text>` | `AGENT_ARTIFACTS_FORMAT`     | Output format                                     |
| `--ndjson`              |                              | Stream list results as NDJSON                     |
| `--quiet`               |                              | Suppress progress messages on stderr              |
| `--no-input`            | `AGENT_ARTIFACTS_NO_INPUT=1` | Disable prompts and browser login                 |
| `--debug`               | `AGENT_ARTIFACTS_DEBUG=1`    | Print stack traces                                |
| `--dry-run`             |                              | Preview mutating commands without calling the API |
| `--version`             |                              | Print CLI version                                 |

## Discovery

| Command            | Purpose                                        |
| ------------------ | ---------------------------------------------- |
| `artifacts schema` | Print machine-readable command catalog         |
| `artifacts health` | Check the API is reachable (`GET /api/health`) |
| `artifacts status` | Show local auth/config state (no network call) |
| `artifacts whoami` | Call `GET /api/profile/me`                     |

## Auth and Profile

`artifacts login` saves a bearer token to `~/.config/agent-artifacts/credentials.json` (mode `0600`) and stays signed in across runs. There is no dependency on an OS keyring, so it behaves identically on workstations, headless servers, containers, CI, and AI agents. Token precedence is `--token` flag → `AGENT_ARTIFACTS_TOKEN` env → saved login file.

| Command                                                | Purpose                                                                   |
| ------------------------------------------------------ | ------------------------------------------------------------------------- |
| `artifacts login`                                      | Browser OAuth login; persists credentials locally                         |
| `artifacts logout`                                     | Revoke the issued key (best effort) and delete the local credentials file |
| `artifacts status`                                     | Report whether you are signed in, the token source, and the active URLs   |
| `artifacts profile get`                                | Read current profile                                                      |
| `artifacts profile set-username --username <username>` | Claim username and personal workspace slug                                |

## API Keys

| Command                                                 | API                              |
| ------------------------------------------------------- | -------------------------------- |
| `artifacts keys list`                                   | `GET /api/api-keys`              |
| `artifacts keys create --name <name> --scopes <scopes>` | `POST /api/api-keys`             |
| `artifacts keys revoke --api-key-id <id>`               | `DELETE /api/api-keys/:apiKeyId` |

Valid scopes:

```text theme={"theme":"github-dark"}
artifacts:read
artifacts:create
artifacts:update
artifacts:delete
artifacts:share
artifacts:access:read
artifacts:access:write
agents:manage
```

## Projects

| Command                                                             | API                                                |
| ------------------------------------------------------------------- | -------------------------------------------------- |
| `artifacts project list --limit 50`                                 | `GET /api/profile/projects`                        |
| `artifacts project create --json '{...}'`                           | `POST /api/projects`                               |
| `artifacts project slug-availability --owner <owner> --slug <slug>` | `GET /api/projects/slug-availability/:owner/:slug` |

Create body:

```json theme={"theme":"github-dark"}
{
  "ownerUsername": "alice",
  "slug": "default",
  "title": "Default",
  "description": "Optional",
  "icon": "*"
}
```

## Workspaces

| Command                                                         | API                                                    |
| --------------------------------------------------------------- | ------------------------------------------------------ |
| `artifacts workspace list`                                      | `GET /api/workspaces`                                  |
| `artifacts workspace members --workspace-id <id>`               | `GET /api/workspaces/:workspaceId/members`             |
| `artifacts workspace invite --workspace-id <id> --json '{...}'` | `POST /api/workspaces/:workspaceId/invitations`        |
| `artifacts workspace revoke-invite --invitation-id <id>`        | `POST /api/workspace-invitations/:invitationId/revoke` |
| `artifacts workspace audit --workspace-id <id>`                 | `GET /api/workspaces/:workspaceId/audit-events`        |

Invitation body:

```json theme={"theme":"github-dark"}
{
  "email": "teammate@example.com",
  "role": "member"
}
```

## Artifacts

| Command                                                                                       | API                                                               |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `artifacts push --owner <owner> --project-slug <slug> --file <path>`                          | `POST /api/artifacts`                                             |
| `artifacts artifact list --limit 50`                                                          | `GET /api/profile/artifacts`                                      |
| `artifacts artifact create --json '{...}'`                                                    | `POST /api/artifacts`                                             |
| `artifacts artifact get --artifact-id <id>`                                                   | `GET /api/artifacts/:artifactId`                                  |
| `artifacts artifact update --artifact-id <id> --json '{...}'`                                 | `POST /api/artifacts/:artifactId/versions`                        |
| `artifacts artifact restore --artifact-id <id> --version <n>`                                 | `POST /api/artifacts/:artifactId/versions/:versionNumber/restore` |
| `artifacts artifact delete --artifact-id <id> --yes`                                          | `DELETE /api/artifacts/:artifactId`                               |
| `artifacts artifact content --artifact-id <id> --version <n>`                                 | `GET /api/artifacts/:artifactId/content`                          |
| `artifacts artifact versions --artifact-id <id>`                                              | `GET /api/artifacts/:artifactId/versions`                         |
| `artifacts artifact diff --artifact-id <id> --from <n> --to <n>`                              | `GET /api/artifacts/:artifactId/diff`                             |
| `artifacts artifact slug-availability --owner <owner> --project-slug <project> --slug <slug>` | `GET /api/artifacts/slug-availability/:owner/:projectSlug/:slug`  |
| `artifacts artifact url-preview --owner <owner> --project-slug <project> --slug <slug>`       | `GET /api/slug-preview/:owner/:projectSlug/:slug`                 |
| `artifacts artifact access get --artifact-id <id>`                                            | `GET /api/artifacts/:artifactId/access`                           |
| `artifacts artifact access set --artifact-id <id> --json '{...}'`                             | `PATCH /api/artifacts/:artifactId/access`                         |

Create body:

```json theme={"theme":"github-dark"}
{
  "ownerUsername": "alice",
  "projectSlug": "default",
  "slug": "readme",
  "type": "md",
  "title": "Readme",
  "description": "Optional",
  "content": "# Hi",
  "changelog": "Initial publish",
  "access": {
    "publicView": true,
    "publicEdit": false
  }
}
```

Update body:

```json theme={"theme":"github-dark"}
{
  "content": "# Updated",
  "changelog": "Optional",
  "expectedLatestVersion": 2
}
```

Access body:

```json theme={"theme":"github-dark"}
{
  "publicView": false,
  "publicEdit": false,
  "viewerEmails": ["teammate@example.com"]
}
```

## Paths

| Command                                                                          | API                                          |
| -------------------------------------------------------------------------------- | -------------------------------------------- |
| `artifacts path project --owner <owner> --project-slug <slug>`                   | `GET /api/by-path/:owner/:projectSlug`       |
| `artifacts path artifact --owner <owner> --project-slug <project> --slug <slug>` | `GET /api/by-path/:owner/:projectSlug/:slug` |

## Share Links and Audit

| Command                                                   | API                                           |
| --------------------------------------------------------- | --------------------------------------------- |
| `artifacts share create --artifact-id <id> --role viewer` | `POST /api/artifacts/:artifactId/share-links` |
| `artifacts share list --artifact-id <id>`                 | `GET /api/artifacts/:artifactId/share-links`  |
| `artifacts share revoke --share-link-id <id>`             | `POST /api/share-links/:shareLinkId/revoke`   |
| `artifacts audit list --artifact-id <id> --limit 50`      | `GET /api/audit-events`                       |

Share link body:

```json theme={"theme":"github-dark"}
{
  "role": "viewer",
  "expiresAt": "2026-06-30T12:00:00.000Z"
}
```