# Getting Started

Install the CLI, check auth, publish, and hand off your first Artifact.

Human page: /docs/getting-started
Markdown page: /docs/getting-started.md

## Install

Use `npx` when Node.js 24 is available, or install the standalone binary when you want one file with no Node runtime.

```sh
npx @zaks-io/agent-paste publish ./report
curl -fsSL https://agent-paste.sh/install.sh | sh
```

```powershell
irm https://agent-paste.sh/install.ps1 | iex
```

The installers verify release checksums before placing `agent-paste` on your PATH. The macOS binary is codesigned and notarized.

## Authenticate

For interactive use, run `agent-paste login`. It opens a browser OAuth flow, mints a scoped API Key, and stores it in your OS keyring when available.

```sh
agent-paste login
agent-paste whoami
```

For CI or a headless agent, set `AGENT_PASTE_API_KEY`. The CLI never accepts secrets as flags. If both a stored login and `AGENT_PASTE_API_KEY` exist, the environment key wins.

Agents should run `agent-paste whoami` before falling back to accountless publish. A successful `whoami` means use normal authenticated publish, not `--ephemeral`.

## Publish

```sh
agent-paste publish ./report
agent-paste publish ./report --artifact-id art_01H...
```

A publish walks a file or folder, creates an Upload Session, uploads bytes to signed upload-worker URLs, finalizes a Revision, publishes it, and returns `artifact_id`, `artifact_url`, `revision_content_url`, and `agent_view_url`. Artifact lifetime comes from Workspace policy, not a CLI flag.

A folder entrypoint is inferred from `index.html`, `index.md`, `README.md`, or the only file in the folder. Pass `--entrypoint` when that is not enough.

For a stable link that follows later publishes, use the Artifact URL. The direct `usercontent.agent-paste.sh/v/...` URL points at one Revision and does not Live Update.

## Ephemeral fallback

```sh
npx @zaks-io/agent-paste publish ./report --ephemeral
```

`--ephemeral` self-provisions a short-lived Ephemeral Workspace and key, publishes once, and prints a one-time Claim Token as `/claim#<token>`. It ignores stored login and `AGENT_PASTE_API_KEY`, so use it only when auth is unavailable or explicitly skipped. Ephemeral is not the Free Plan: use it for non-interactive text, markdown, images, and static HTML/CSS. Unclaimed ephemeral HTML is script-disabled, so use authenticated publish for interactive work.