# Getting Started

Get up and running with ML-Dash in under 5 minutes.

## Installation

```bash
pip install ml-dash
```

## Your First Experiment (Local)

Local mode stores everything on your filesystem — no account, no network, perfect for trying things out.

```python
from ml_dash import Experiment

# Prefix format: owner/project/experiment-name
with Experiment(
    prefix="alice/tutorial/my-first-experiment",
    dash_root=".dash",
).run as exp:
    exp.log("Training started", level="info")

    exp.params.set(
        learning_rate=0.001,
        batch_size=32,
        epochs=10,
    )

    for epoch in range(10):
        loss = 1.0 - epoch * 0.08
        exp.metrics("train").log(loss=loss, epoch=epoch)

    exp.log("Training completed", level="info")
```

Your data lives in `.dash/alice/tutorial/my-first-experiment/`:

```
.dash/
└── alice/                              # owner
    └── tutorial/                       # project
        └── my-first-experiment/        # experiment
            ├── logs/logs.jsonl
            ├── parameters/parameters.json
            └── metrics/train/data.jsonl
```

## Your First Experiment (Remote)

Ready to sync to the ML-Dash server? Authenticate once, then pass a `dash_url`.

### 1. Authenticate

```bash
ml-dash login
```

This opens your browser for OAuth2 and stores a token in your system keychain.

### 2. Run with `dash_url`

```python
from ml_dash import Experiment

with Experiment(
    prefix="alice/my-project/training-run",
    dash_url="https://api.dash.ml",  # token auto-loaded from keychain
).run as exp:
    exp.log("Running on remote server", level="info")
    exp.params.set(learning_rate=0.001)

    for epoch in range(10):
        loss = 1.0 - epoch * 0.08
        exp.metrics("train").log(loss=loss, epoch=epoch)
```

The API is identical — only the constructor args change.

## Next Steps

- **Concepts**: read the [Overview](/index.md) for the mental model
- **Feature guides**: [Logging](/logging.md), [Parameters](/parameters.md), [Metrics](/metrics.md), [Files](/files.md)
- **Going deeper**: [Experiments](/experiments.md) for advanced patterns (training loops, file uploads, tracks)

Using [Claude Code](https://claude.ai/download)? Install the companion plugin for in-editor help: `/plugin marketplace add fortyfive-labs/ml-dash` then `/plugin install ml-dash@ml-dash`.

## Install the docs as a skill

These docs ship as an [Agent Skill](/llm-readable.md) so your agent can answer
ML-Dash questions accurately — without you pasting context. Install it once and
Claude loads it on demand.

**Claude Code — this project only** (drop it in the project's skills dir):

```bash
curl -L https://docs.dash.ml/skills/dash-docs.zip -o dash-docs.zip
unzip dash-docs.zip -d .claude/skills/ && rm dash-docs.zip
```

**Claude Code — every project** (install under your home config):

```bash
curl -L https://docs.dash.ml/skills/dash-docs.zip -o dash-docs.zip
unzip dash-docs.zip -d ~/.claude/skills/ && rm dash-docs.zip
```

The skill is `dash-docs/` with a `SKILL.md` and one markdown reference file
per docs page. It's regenerated on every deploy, so it never drifts from the
site.

> **Note:** **No install needed for one-off questions.** Point any agent at
> [`https://docs.dash.ml/llms.txt`](https://docs.dash.ml/llms.txt)
> (an index) or `https://docs.dash.ml/llms-full.txt` (the whole site in one
> file). See [LLM-Readable Docs](/llm-readable.md) for all the ways to consume these
> docs as markdown.