Skip to content

Install and sign in

View as Markdown · Docs for agents

Install mr-data, approve the device in your browser and connect the CLI to the hosted backend.

Install

Section titled “Install”

The package is mostlyright-data. The command it installs is mr-data.

Terminal window
python -m pip install mostlyright-data

Or as a standalone tool, with its own interpreter:

Terminal window
uv tool install mostlyright-data

The package needs CPython 3.11 or newer and has no third-party dependencies, compiled extensions or Docker image. It runs on Linux, macOS and Windows because all builds execute on the hosted backend.

Check what you got:

Terminal window
mr-data --version
mr-data 0.19.2

Everything runs on the backend

Section titled “Everything runs on the backend”

mr-data sends requests to the hosted backend and prints the results. The hosted worker fetches and parses sources, runs the SQL and checks, then writes the Parquet files. The run receipt records what happened during the build.

  • A command that reaches the backend needs a signed-in device credential. mr-data --version, mr-data --help and mr-data dataset categories do not.
  • Building is free with a signed-in account. Reading data past the free sample counts against a monthly allowance. See What counts against the allowance.

Sign in

Section titled “Sign in”
Terminal window
mr-data login

This is an RFC 8628 device flow against https://mostlyright.md:

  1. The command prints a short user code on stderr and an address to approve it at, then tries to open that address in your browser. On a headless machine, open it yourself.
  2. You approve the device in the browser as the signed-in user.
  3. The command creates and stores a device key.
    WDJB-MJHT


Open https://mostlyright.md/device?user_code=WDJB-MJHT to approve this device.
Waiting for approval...

The key is stored in ~/.mostlyright/credentials with mode 0600. The command prints its mr_cli_ prefix and last four characters, but never the raw key. If a credential already exists, login returns LOGIN_CREDENTIALS_EXIST. Use mr-data auth rotate to replace it. Rotation revokes the old key remotely before removing the local copy.

Two more flags: --device-name NAME, which defaults to the machine’s hostname, and --credential-store secure-file. Set MOSTLYRIGHT_CLOUD_URL to sign in against a different deployment.

Check the credential

Section titled “Check the credential”
Terminal window
mr-data auth status --json

mr-data whoami is the compatibility alias for the same thing. Both validate the effective credential with Cloud and report stored metadata separately. Neither prints a credential.

{
  "schema_version": "mr-data-auth-status.v1",
  "status": "authenticated",
  "effective_source": "stored_device",
  "remote_validation": "validated",
  "device": {
    "id": "zn0aFEzQjXzOH16F01VcWO4a5rg3NQTZ",
    "name": "my-laptop",
    "prefix": "mr_cli_",
    "last_four": "wunu",
    "created_at": "2026-08-19T20:25:49.647Z",
    "last_used_at": "2026-09-12T08:08:20.372Z"
  },
  "identity": {
    "cloud": { "organization_id": "WQUz...", "user_id": "VQGT...", "role": "owner" },
    "studio": {
      "principal_id": "8801ad48-56aa-564a-87e3-65ca7bd1fc3c",
      "workspace_id": "39ffafde-86ed-5d7b-b337-1c205ea79390"
    }
  },
  "stored_state": {
    "status": "available",
    "device": { "cloud_url": "https://mostlyright.md", "key_id": "zn0a...", "prefix": "mr_cli_" }
  }
}

status is authenticated, refused or error. A refusal includes error_code instead of identity. A rate-limit refusal also includes retry_after_seconds.

The rest of mr-data auth is devices, tokens, rotate, logout and recover. devices reports the device metadata Cloud holds. tokens says what the Studio transport token is and is not. logout revokes remotely, then removes locally. recover resumes or clears an interrupted credential write.

MOSTLYRIGHT_API_KEY in the environment takes precedence over the stored device key for that process. auth status says so in environment_notice. mr-data cannot unset a credential a parent process put in the environment.

Where the agent skill goes

Section titled “Where the agent skill goes”

The package includes the mr-data-build agent skill. The first mr-data command copies it into your agent’s personal skill directory:

~/.claude/skills/mr-data-build/

Codex gets the same tree at ~/.codex/skills/mr-data-build/. CLAUDE_CONFIG_DIR and CODEX_HOME move those roots. mr-data leaves a skill you have edited alone. A read-only home or a full disk returns a reason and does not fail your command.

Turn the copy off with MOSTLYRIGHT_SKILL_AUTOINSTALL=0:

Terminal window
MOSTLYRIGHT_SKILL_AUTOINSTALL=0 mr-data status RUN_ID

What counts against the allowance

Section titled “What counts against the allowance”

Building is free with an account: datasets, recipes, runs and refreshes. Any signed-in workspace can run every mr-data build command.

The first 500 rows of every table, in stored order, are free to everyone. Past them, a free workspace may read 100,000 rows and run 1,000 queries a UTC month, shared by all of its members. A query costs one query plus the rows it returns, and that includes mr-data query over your own runs. A download, including mr-data download, counts the rows it contains, plus one query per table. A download whose size is known in advance and would take you past your free rows is not started: the 402 below then also carries remaining and requested. A page of a table’s parts is cut to the parts that fit instead, with truncated: true. A subscribed workspace is never counted, for anyone working in it.

A spent allowance answers HTTP 402 with one body on every API, CLI and MCP path:

{"schema_version":"mostlyright-usage-limit.v1","error":"usage_limit_exceeded","unit":"rows","limit":100000,"used":100250,"resets_at":"2026-11-01T00:00:00.000Z","upgrade_url":"https://mostlyright.md/dashboard/billing","detail":"You have used 100,250 of 100,000 free rows this month. Upgrade the workspace or wait for the reset. The first rows of every table stay free."}

mr-data prints this as THIN_USAGE_LIMIT. Subscribe at upgrade_url or wait for resets_at. Two other errors have different causes. THIN_AUTHENTICATION_FAILED is HTTP 401 and means the stored key was rejected, so sign in again. THIN_STUDIO_UNAVAILABLE is HTTP 503 and means you should try later.

The --json convention

Section titled “The --json convention”

Every command takes --json and prints exactly one machine-readable JSON object on stdout. It is a per-command flag, written after the command name:

Terminal window
mr-data dataset categories --json
mr-data status RUN_ID --json

Every object includes a schema_version for its shape and a status for the outcome: dataset_created, recipe_registered, run_queued, run_status_reported, checks_reported, query_answered, artifacts_downloaded. The CLI keys and zero-pads repeated items rather than listing them, so expect {"row 01": …, "row 02": …} where a list would be.

Exit codes: 0 on success, 2 where the answer is a gate a script must act on. A run held at the run confirmation, a failed run read by status and a table that disagrees with its manifest all exit 2. An error prints a code and a detail. The CLI produces codes beginning THIN_ before it sends anything. Other codes come directly from the backend. Run states and errors lists them.

Two more environment variables matter. MR_DATA_NO_ACTIVITY=1 stops commands reporting what they are doing to the dataset page, and --no-activity does the same for one invocation. MOSTLYRIGHT_CLOUD_URL points the whole client at another deployment.

Next

Section titled “Next”