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

# Quickstart

> Push, list, and pull your first artifact in 60 seconds.

## Get your API key

Sign up at [app.artifacta.io](https://app.artifacta.io/signup) and copy your API key from the onboarding screen. Keys start with `ak_live_`.

<Warning>
  Your full API key is shown only once at creation time. Copy it immediately.
</Warning>

## Install

<CodeGroup>
  ```bash pip theme={null}
  pip install artifacta-cli
  ```

  ```bash Homebrew theme={null}
  brew install artifacta/tap/artifacta
  ```

  ```bash curl theme={null}
  curl -fsSL https://get.artifacta.io | sh
  ```
</CodeGroup>

`pip install artifacta-cli` gives you both the CLI and the Python SDK.

## Authenticate

<Tabs>
  <Tab title="Environment variable (recommended)">
    ```bash theme={null}
    export ARTIFACTA_API_KEY="ak_live_abc123..."
    ```

    Best for agents and CI — every sub-process inherits the key automatically.
  </Tab>

  <Tab title="CLI login">
    ```bash theme={null}
    # Interactive prompt
    artifacta auth login

    # Or pipe the key in (CI / agents) — won't hang on empty stdin
    echo "$ARTIFACTA_API_KEY" | artifacta auth login
    ```

    Stores the key in `~/.config/artifacta/config.toml`.
  </Tab>
</Tabs>

Verify it works:

```bash theme={null}
artifacta whoami
```

```text Output theme={null}
Tenant:  acme-corp
Plan:    free
Key:     ...k9f7 (last 4)
Usage:   0 / 10,000 requests this month
Storage: 0 B / 1 GB
```

## Push → List → Pull

<Steps>
  <Step title="Push a file">
    Upload an artifact tagged with a session ID.

    ```bash theme={null}
    artifacta push report.pdf --session demo-run
    ```

    ```text Output theme={null}
    ✓ Uploaded art_2xk9f7v3m1p0
      Filename:  report.pdf
      Size:      245 KB
      Hash:      sha256:e3b0c44298fc1c149afbf4c8996fb9...
      Expires:   2026-04-28T10:30:00+00:00
    art_2xk9f7v3m1p0
    ```

    The human-readable block prints to stderr; the trailing artifact ID prints to stdout so you can pipe it: `artifacta push report.pdf | xargs artifacta pull`.
  </Step>

  <Step title="List artifacts in the session">
    ```bash theme={null}
    artifacta ls --session demo-run
    ```

    ```text Output theme={null}
    ARTIFACT ID         FILENAME            SIZE     CREATED              EXPIRES
    art_2xk9f7v3m1p0   report.pdf          245 KB   2026-03-29 10:30     2026-04-28

    1 artifact, 245 KB total
    ```
  </Step>

  <Step title="Pull the artifact back">
    ```bash theme={null}
    artifacta pull art_2xk9f7v3m1p0
    ```

    ```text Output theme={null}
    ✓ Downloaded report.pdf (245 KB)
      Saved to: ./report.pdf
    ```
  </Step>
</Steps>

That's it. Your artifact is stored, deduplicated, and will auto-expire in 30 days.

## Do the same thing in Python

```python theme={null}
from artifacta import Client

client = Client()  # reads ARTIFACTA_API_KEY from environment

# Push
artifact = client.push("report.pdf", session_id="demo-run")
print(artifact.id)  # art_2xk9f7v3m1p0

# List
for a in client.list(session_id="demo-run"):
    print(f"{a.id}: {a.filename}")

# Pull
client.pull(artifact.id, output="./downloads/")
```

## What to try next

<CardGroup cols={2}>
  <Card title="Multi-Agent Pipeline" icon="diagram-project" href="/guides/multi-agent-pipeline">
    Coordinate artifact handoffs across agents using sessions and metadata.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Full reference for every CLI command, flag, and environment variable.
  </Card>

  <Card title="Python SDK" icon="python" href="/sdk/overview">
    Push dicts, pull bytes, and manage sessions from Python.
  </Card>

  <Card title="REST API" icon="code" href="/api/overview">
    Integrate from any language with the REST API.
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="https://artifacta.io/use-cases">
    See end-to-end patterns: client-ready reports, scheduled publishing, agent-to-agent handoff.
  </Card>

  <Card title="Blog" icon="newspaper" href="https://artifacta.io/blog">
    Deep dives on agent artifact workflows.
  </Card>
</CardGroup>

<Info>
  **Agent integration tip:** Set `ARTIFACTA_SESSION_ID` in the environment before spawning sub-agents.
  Every agent inherits the session automatically — zero flag passing required.
</Info>