# Mock datasets

> Give a prototype realistic sample users, products, or orders before connecting a real service.
> URL: https://artor.app/docs/mock

Fill a prototype with realistic sample users, products, or orders before connecting a real
service. Mock datasets are available on **every plan**, including Starter.

## Add sample data

Save your sample data as a JSON file, such as `users.json`. JSON is a text format for lists and
other structured data; your coding agent can create the file for you.

From your linked project folder, run:

```bash
artor mock set users users.json
artor publish
```

Ask your coding agent to have the prototype load its sample users from `/__mock/users`.
Adding a dataset doesn't automatically connect it to your interface. If you need help with
the terminal, start with [Installing the CLI](https://artor.app/docs/install-cli).

## Where a mock can live

| Location | Use it for |
| --- | --- |
| Organization | Shared sample data used by multiple prototypes; add `--scope org`. |
| Project | Data for one prototype; the default in a linked project folder. |
| Version | Data for one published version; add `--version v3`. |
| Local files | Data you edit alongside your prototype in `mocks/`. |

A prototype's own data takes priority over the organization's default. When publishing,
local files included in the build take priority, unless you choose the server's copy when
Artor asks about a conflict.

### How many, and how big

Each organization, project, and version can have **50 datasets**, with **2 MB per dataset**.
Replacing an existing name does not use another slot. These limits are the same on every plan.

## Seeds vs. published versions (the snapshot rule)

Organization and project datasets are starting points for future publishes. Editing them
**does not update an already-published version**. Publish again to use the updated data.

A published version keeps its chosen data unless someone explicitly changes that version's
dataset. This lets you update shared sample data without changing an earlier review by accident.

### Repointing a published version: `mock pin`

To deliberately replace a published version's data with an earlier saved revision:

```bash
artor mock revisions users
artor mock pin users <sha> --version v3
```

Copy the revision identifier shown by `revisions` into `<sha>`. It must be an existing
revision of that dataset. This changes the data reviewers see on v3 **without republishing**,
so use it only when you intend to change that version's review.

You can also target a version directly with `mock set` or `mock rm`; those changes affect
that version rather than the project's starting data.

## Working with local files

```bash
artor mock status          # compare local and saved data without changing files
artor mock pull            # download the project's data into ./mocks/*.json
```

`pull` uses the project's data and organization defaults. **It overwrites matching local
files that differ**, so check `status` first if you have edits to keep. Status identifies
files that are only local, only saved in Artor, or different in the two places.

### Promoting a version's mock to the org

When a version contains a dataset the whole team should use as a default:

```bash
artor mock promote users --ref latest  # admin access required
```

This copies the `users` file included with that version to the organization's shared data.
It requires an owner/admin with a publisher seat and fails if the version has no bundled file
with that name. Existing published versions stay unchanged.

## The publish-time drift gate

If a local dataset differs from the copy saved in Artor, publishing asks which to use:
**keep local** or **use server**. To choose the same answer for every conflict:

```bash
artor publish --mocks=local
artor publish --mocks=server
```

Without a terminal to ask you, publishing stops at a conflict until you choose a flag.
It also asks for a choice if it cannot check the saved data. A dataset present only in one
place is not a conflict.

## Who can do what

- **Set or remove organization data:** owners and admins.
- **Set, remove, or pin project/version data:** publishers with permission to edit the
  prototype's [Space](https://artor.app/docs/spaces).
- **List, view revisions, pull, or compare data:** organization members with access to the
  prototype.
- **Promote to the organization:** owners and admins with a publisher seat.

`set`, `list`, and `rm` use project scope in a linked folder; outside one, use `--scope org`.
`revisions` supports project or organization scope. `pull`, `status`, and `promote` use the
linked project and do not accept scope flags; `promote` selects its version with `--ref`.
See the [CLI reference](https://artor.app/docs/cli#mock-datasets) for the complete command list.

## Bundling a mock with a build

Keep sample data beside your code in `mocks/users.json` or `mocks/products.json`, and include
that folder in the build you publish. Your prototype can then load `/__mock/users` or
`/__mock/products`.

Use letters, numbers, hyphens, and underscores in dataset names, up to 64 characters.
If a file is too large or isn't valid JSON, publishing warns you. The file may still be
available in the preview, but it isn't saved as a dataset revision. Fix it and publish again
before relying on its revision history.

## Not for secrets

**Warning:** 
  Use invented sample data. Don't put real credentials or private customer information in a
  dataset: people who can open the prototype may be able to read it. Use
  [environment variables](https://artor.app/docs/env) for configuration, following their credential guidance.

Changes to datasets appear in the [audit log](https://artor.app/docs/audit-log).

## Related

- [Environment variables](https://artor.app/docs/env) — configuration for your prototype
- [Publishing & frameworks](https://artor.app/docs/publishing) — publish and resolve data conflicts
- [CLI reference](https://artor.app/docs/cli#mock-datasets) — every command and flag