Use the CLI

The clinder command-line tool starts and stops BinderHub sessions from your own machine or scripts. If you’re using this as part of CI/CD in GitHub, see Use the GitHub Action.

Install¶

npm install -g clinder

Start a session¶

clinder start https://mybinder.org/ --github-repo binder-examples/requirements

This streams the Binder build logs and, once the server is ready, prints its URL and token.

Usage: clinder start [options] <binderhub <url>>

Arguments:
  binderhub <url>       BinderHub URL

Options:
  --github-repo <repo>  GitHub repo
  --github-ref <ref>    GitHub ref (default: "HEAD")
  --json                Output JSON
  --build-token         BinderHub build token
  -h, --help            display help for command

Save the environment variabels for re-use¶

Use --json to print {"url": ..., "token": ...} on stdout so you can save to disk (the build logs will then be sent to stderr):

clinder start https://mybinder.org/ --github-repo binder-examples/requirements --json > session.json

Unlike the GitHub Action, the CLI does not set environment variables automaitcally, so export the connection info yourself for the examples below:

export JUPYTER_BASE_URL=$(jq -r .url session.json)
export JUPYTER_TOKEN=$(jq -r .token session.json)

Open JupyterLab in the session¶

The session is a full Jupyter server, so the quickest demo is to open its JupyterLab in your browser:

open "${JUPYTER_BASE_URL}lab?token=${JUPYTER_TOKEN}"  # macOS; use xdg-open on Linux

Execute a MyST or Jupyter Book project¶

MyST and Jupyter Book execute against the session whenever JUPYTER_BASE_URL and JUPYTER_TOKEN are set, with no extra configuration:

myst build --html --execute

The build log shows MyST connecting to the Binder kernel rather than starting a local one, and the page outputs are computed on the Binder pod. The live demo uses this pattern in CI to build these docs.

Execute on non-GitHub build platforms¶

To use clinder on platforms other than GitHub Actions, you can follow the logic above with other CI/CD configuration. For example, you could host your website on Netlify to get Pull Request previews and use configuration like the following: On Netlify, in netlify.toml:

[build]
  publish = "_build/html"
  command = """
  npm install -g mystmd clinder && \
  clinder start https://mybinder.org/ --github-repo org/repo --json > session.json && \
  export JUPYTER_BASE_URL=$(jq -r .url session.json) JUPYTER_TOKEN=$(jq -r .token session.json) && \
  myst build --html --execute && \
  clinder stop "$JUPYTER_BASE_URL" "$JUPYTER_TOKEN"
  """

On Read the Docs, in .readthedocs.yaml (each command runs in a separate shell, so the session must start, build, and stop within one command):

version: 2

build:
  os: ubuntu-24.04
  tools:
    nodejs: "22"
  commands:
    - npm install -g mystmd clinder
    - >
      clinder start https://mybinder.org/ --github-repo org/repo --json > session.json
      && export JUPYTER_BASE_URL=$(jq -r .url session.json) JUPYTER_TOKEN=$(jq -r .token session.json)
      && myst build --html --execute
      && clinder stop "$JUPYTER_BASE_URL" "$JUPYTER_TOKEN"
    - mkdir -p $READTHEDOCS_OUTPUT && cp -r _build/html $READTHEDOCS_OUTPUT/html

If a build fails before reaching clinder stop, the session is cleaned up by the BinderHub’s inactivity timeout.

Stop a session¶

Pass the URL and token printed by clinder start:

clinder stop <url> <token>

For example, reading them from the session.json written above:

clinder stop "$(jq -r .url session.json)" "$(jq -r .token session.json)"

Binder sessions time out after a period of inactivity, but shutting them down explicitly frees resources for other users.