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

# Artifacts

> Working with files and outputs from your crew runs

## Overview

Artifacts are files produced by your crew during a run. Crewship automatically:

* Collects files from a standard directory
* Stores them durably
* Makes them accessible via API and Console

## Producing Artifacts

Write files to the `artifacts/` directory:

<CodeGroup>
  ```python Python (CrewAI / LangGraph) theme={null}
  # Write files directly from your agent or node
  with open("artifacts/report.md", "w") as f:
      f.write(generated_content)
  ```

  ```typescript TypeScript (LangGraph.js) theme={null}
  import { writeFileSync } from 'fs'
  import { mkdirSync } from 'fs'

  mkdirSync('artifacts', { recursive: true })
  writeFileSync('artifacts/report.md', generatedContent)
  ```
</CodeGroup>

With CrewAI, you can also use the `output_file` parameter on a task:

```yaml tasks.yaml theme={null}
writing_task:
  description: Write a comprehensive report about {topic}
  expected_output: A detailed markdown report
  agent: writer
  output_file: artifacts/report.md
```

Produce as many files as needed:

```python theme={null}
with open("artifacts/summary.md", "w") as f:
    f.write(summary)

with open("artifacts/data.json", "w") as f:
    json.dump(data, f)

with open("artifacts/chart.png", "wb") as f:
    f.write(image_bytes)
```

## Accessing Artifacts

### Via CLI

```bash theme={null}
# List artifacts for a run
crewship runs artifacts run_xyz789
```

Output:

```
Artifacts for run_xyz789:

  report.md        3.2 KB   text/markdown
  data.json        1.1 KB   application/json
  chart.png       45.6 KB   image/png

3 artifacts, 49.9 KB total
```

Download artifacts:

```bash theme={null}
# Download single artifact
crewship runs download run_xyz789 report.md

# Download all artifacts
crewship runs download run_xyz789 --all

# Download to specific directory
crewship runs download run_xyz789 report.md --output ./downloads/
```

### Via API

```bash theme={null}
# List artifacts
curl https://api.crewship.dev/v1/runs/run_xyz789/artifacts \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "artifacts": [
    {
      "name": "report.md",
      "size": 3276,
      "content_type": "text/markdown",
      "created_at": "2024-01-15T10:30:46Z"
    },
    {
      "name": "data.json",
      "size": 1124,
      "content_type": "application/json",
      "created_at": "2024-01-15T10:30:46Z"
    }
  ]
}
```

Download an artifact:

```bash theme={null}
curl https://api.crewship.dev/v1/runs/run_xyz789/artifacts/report.md \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o report.md
```

### Via Console

1. Open the [Console](https://console.crewship.dev)
2. Navigate to your run
3. Click the **Artifacts** tab
4. Click any artifact to preview or download

## Artifact Events

When an artifact is produced, an event is emitted:

```json theme={null}
{
  "type": "artifact",
  "payload": {
    "name": "report.md",
    "size": 3276,
    "content_type": "text/markdown",
    "sha256": "abc123..."
  }
}
```

Use this for real-time notifications in streaming:

```bash theme={null}
crewship invoke --input '{"topic": "AI"}' --stream
# ...
├─ [10:30:46] Artifact: report.md (3.2 KB)
```

## Supported File Types

Any file type is supported. Common types include:

| Type      | Extensions             | Use Case            |
| --------- | ---------------------- | ------------------- |
| Text      | `.md`, `.txt`, `.csv`  | Reports, logs, data |
| JSON      | `.json`                | Structured data     |
| Documents | `.pdf`, `.docx`        | Formatted output    |
| Images    | `.png`, `.jpg`, `.svg` | Charts, screenshots |
| Archives  | `.zip`, `.tar.gz`      | Bundled outputs     |

## Size Limits

| Limit           | Value   |
| --------------- | ------- |
| Single artifact | 100 MB  |
| Total per run   | 500 MB  |
| Retention       | 30 days |

<Note>Need larger limits? [Contact us](mailto:support@crewship.dev) for enterprise plans.</Note>

## Organizing Artifacts

Use subdirectories for organization:

```python theme={null}
with open("artifacts/reports/summary.md", "w") as f:
    f.write(summary)

with open("artifacts/data/output.json", "w") as f:
    json.dump(data, f)
```

Artifacts are listed with their relative paths:

```
reports/summary.md    2.1 KB
data/output.json      1.5 KB
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive names">
    Name files clearly: `quarterly_report_2024Q1.md` not `output.md`
  </Accordion>

  <Accordion title="Include metadata">
    Add timestamps or run info to filenames when helpful:

    ```python theme={null}
    filename = f"report_{run_id}_{timestamp}.md"
    ```
  </Accordion>

  <Accordion title="Use appropriate formats">
    * Markdown for human-readable reports
    * JSON for structured data
    * CSV for tabular data
    * PDF for formatted documents
  </Accordion>

  <Accordion title="Compress large outputs">
    For many files, create a zip archive:

    ```python theme={null}
    import zipfile

    with zipfile.ZipFile("artifacts/bundle.zip", "w") as zf:
        for file in files:
            zf.write(file)
    ```
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Your First Crew" icon="rocket" href="/guides/your-first-crew">
    Build a crew that produces artifacts
  </Card>

  <Card title="Streaming" icon="bolt" href="/guides/streaming">
    Get notified when artifacts are produced
  </Card>
</CardGroup>