CLI setup and authentication

CyteType requires an API key before a client can upload artifacts, submit an annotation, or fetch remote results. For local work, the recommended setup is passwordless browser sign-in. The Python and R clients use the same credentials file for the same operating-system user, so signing in with either client configures both.

Python setup

The cytetype terminal command is installed with the Python package:

python -m pip install --upgrade cytetype
cytetype setup

cytetype setup validates a saved key for the selected server. If no matching key is available, it opens CyteType sign-in in your browser and prints the same URL in the terminal. Complete sign-in within five minutes.

If a saved key is invalid or you need to sign in as a different account, start a new browser flow without validating the saved key:

cytetype setup --force

Already have an API key from the CyteType Dashboard? Enter it through a hidden prompt:

cytetype login

R setup

CyteTypeR provides the same setup flow as an R function:

library(CyteTypeR)
SetupCyteTypeR()

To replace an invalid saved key or sign in again:

SetupCyteTypeR(force = TRUE)

If you already have a key, validate and save it with a hidden prompt:

LoginCyteTypeR()

LoginCyteTypeR(api_token = ...) also accepts a key directly. Read it from a secret store or environment variable instead of writing it in a shared script.

Optional R terminal command

The R functions are sufficient for authentication. If you also want a terminal command, install the optional cytetyper launcher from R:

InstallCyteTypeRCli()

By default, this copies the launcher beside the active Rscript executable. That directory must be writable and available on PATH for cytetyper to work in a new terminal.

cytetyper setup
cytetyper dashboard
cytetyper view <JOB_ID>

Command reference

The CLIs manage authentication and open browser pages. Annotations are run through the Python or R client, not as a terminal subcommand.

get-key is an alias for setup and accepts the same options. dashboard uses the server associated with saved credentials, or the production dashboard when no credentials exist. view opens the server's sign-in route for the selected report without placing the API key in the URL.

What browser setup does

Browser setup:

1. Starts a temporary callback server on 127.0.0.1 using an available port.
2. Opens and prints a passwordless authorization URL.
3. Verifies the returned state and exchanges a one-time code using PKCE.
4. Saves the API key only after the exchange succeeds.

The API key is not included in the authorization URL or printed in the terminal. If the browser does not open automatically, copy the printed URL while leaving the setup process running. A firewall or browser policy that blocks the callback to 127.0.0.1 will prevent setup from completing.

Running setup again normally validates the saved key instead of opening another browser. --force in either CLI, or force = TRUE in R, skips that validation and starts a new sign-in flow.

Credential storage and security

Python and R store one shared credential set in credentials.json:

The file contains the API key in plain JSON so both clients can authenticate automatically. Do not share it, commit it, or copy it into a notebook. On POSIX systems, the clients set the directory to mode 0700 and the file to mode 0600; they also refuse to write into a credentials directory owned by another user.

Only one server's credentials are stored at a time. Signing in against another server replaces the locally saved set. cytetype logout, cytetyper logout, and LogoutCyteTypeR() remove only the local file. Disable the key in the Dashboard when the server must stop accepting it.

Custom servers

The production server is https://cytetype.nygen.io. Select another server explicitly during setup and use that same origin for annotation:

cytetype setup --api-url https://cytetype.example.org

SetupCyteTypeR(api_url = "https://cytetype.example.org")

The optional R CLI uses the same syntax:

cytetyper setup --api-url https://cytetype.example.org

You can instead configure the default origin for both clients:

export CYTETYPE_API_URL=https://cytetype.example.org

An explicit CLI option or client api_url takes precedence over CYTETYPE_API_URL. The value must be a server origin containing only a scheme, host, and optional port. Non-local servers must use HTTPS. http://localhost and http://127.0.0.1 are allowed for local development.

Saved keys are matched to the selected origin and are not reused for another server.

Remote notebooks, SSH, and CI

Browser setup requires the authorization callback to reach 127.0.0.1 in the environment running the client. It may not work in CI, a hosted notebook, or an SSH session without suitable forwarding.

In an interactive remote terminal, use cytetype login, LoginCyteTypeR(), or cytetyper login with a key created in the Dashboard. For a non-interactive environment, inject the key from the platform's secret store and pass it directly to the client:

import os

from cytetype import CyteType

annotator = CyteType(
    adata,
    group_key="leiden",
    api_url=os.environ.get("CYTETYPE_API_URL", "https://cytetype.nygen.io"),
    auth_token=os.environ["CYTETYPE_API_TOKEN"],
)

result <- CyteTypeR(
  obj = seurat_obj,
  prepped_data = prepped_data,
  study_context = "Human PBMC from a healthy donor",
  api_url = Sys.getenv("CYTETYPE_API_URL", "https://cytetype.nygen.io"),
  auth_token = Sys.getenv("CYTETYPE_API_TOKEN")
)

CYTETYPE_API_TOKEN is an example secret name. Neither client reads it automatically. Avoid command-line arguments for secret values because they may be retained in shell history or process listings.

Authentication precedence

The Python client resolves a key in this order:

1. auth_token passed to run()
2. auth_token passed to the CyteType instance, when it belongs to the selected API origin
3. Saved CLI credentials matching the selected API origin

The R client resolves a key in this order:

1. auth_token passed to CyteTypeR() or the result-fetching call
2. Saved credentials matching the selected API origin

When fetching a previous job, the clients use the API origin stored with that job. In R, an explicit token supplied to GetResults() must be accompanied by the same api_url. If no matching key is available, run setup for that origin or provide a token explicitly.

Learn more

Installation

First annotation

CyteType Dashboard

Security and privacy