Skip to content
Relay

The relay command line

relay is a small command line over Relay’s API. It is for the moments when clicking is the wrong tool: a Snakemake rule that should upload its outputs, a cron job that runs a pipeline every night, a CI step that checks whether a job finished.

Every relay command runs one of the same tools an AI agent would, so it carries the same permissions and limits as the token it uses.

Install and log in

Section titled “Install and log in”

  1. Install

    Terminal window
    npm install -g @relay-science/mcp

    The package also provides the MCP server; relay is the second command it installs.

  2. Create a token

    Settings → Account → API access → New token. Give it only the scopes the machine needs.

  3. Log in

    Terminal window
    relay login --url https://relaysci.com

    Paste the token when asked. relay checks it against the server before saving it to ~/.relay/credentials.json, readable only by you.

On a server or in CI, skip login and set RELAY_API_TOKEN and RELAY_API_URL in the environment instead. They take precedence over the saved file.

Commands

Section titled “Commands”
Terminal window
relay whoami                                # who the token acts as, and its scopes
relay workspaces                            # your workspaces


relay upload ./plate.ome.tiff               # into the root of Relay Drive
relay upload ./plate.ome.tiff --folder plates/2026-09
relay upload ./big.zarr.zip --team <team-id>


relay run pipeline <pipeline-id> --input <asset-ref>
relay run notebook <notebook-id>            # every cell, top to bottom


relay jobs --status processing              # pending, processing, completed, failed, cancelled
relay jobs get <job-id>
relay jobs watch <job-id>                   # returns when the job finishes


relay runs --open                           # Ray runs, in the app and in Slack
relay runs show <run-id>                    # prompt, transcript, cost
relay runs stop <run-id>


relay tools                                 # everything `call` accepts
relay call search_assets --args '{"query":"nuclei"}'

Add --json to any command for the machine-readable result, which is the same structured answer the MCP tool returns:

Terminal window
relay jobs watch "$JOB" --json | jq -r .status
relay upload results.csv --json | jq -r .file.id

Exit codes: 0 on success, 1 when the command ran and failed, 2 for a usage mistake, which is reported before anything is sent.

Examples

Section titled “Examples”

Run a pipeline every night on the day’s plate and file the result. The token lives in the crontab’s environment, never in the command.

Terminal window
# /etc/cron.d/nightly-plate — RELAY_API_TOKEN and RELAY_API_URL set above this line
0 2 * * *  lab  relay upload /data/today/plate.ome.tiff --folder plates --json \
                 | jq -r .file.id \
                 | xargs -I{} relay run pipeline <pipeline-id> --input {}

Upload a rule’s output as soon as it exists.

rule upload_counts:
    input: "results/{sample}.counts.csv"
    output: touch("results/{sample}.uploaded")
    shell: "relay upload {input} --folder counts/{wildcards.sample}"

Fail the build if a job failed.

Terminal window
status=$(relay jobs watch "$JOB_ID" --json | jq -r .status)
[ "$status" = "completed" ] || { echo "job $JOB_ID ended $status"; exit 1; }