Command-line reference

CyteType has two small command-line tools. Both sign you in and open CyteType pages in your browser:

• cytetype is installed with the Python package.

• cytetyper is an optional launcher for the R package. Every cytetyper command is also an R function, so you can do the same things from an R session without installing it.

Neither tool runs annotations. You submit jobs from Python with CyteType.run() and from R with CyteTypeR() (see the Python quickstart and the R quickstart). For a step-by-step guide to signing in, see Sign in and API keys.

Commands at a glance¶

All of these share one saved sign-in (see Saved credentials). Signing in with either tool, or from either package, signs in both clients.

The same commands in the two clients:

cytetype setup            # sign in with the browser
cytetype view <JOB_ID>    # open a report
cytetype logout           # delete the saved key on this computer

library(CyteTypeR)
SetupCyteTypeR()             # sign in with the browser
ViewCyteTypeJob("<JOB_ID>")  # open a report
LogoutCyteTypeR()            # delete the saved key on this computer

cytetype (Python)¶

The cytetype command is installed with the Python package. If your shell cannot find it, activate the environment where cytetype is installed, or run the same commands through Python:

python -m cytetype.cli setup

Usage:

cytetype [-h] [--version] {setup,get-key,login,dashboard,view,logout} ...

Running cytetype without a command prints the help. Options go after the command name: cytetype setup --force, not cytetype --force setup.

cytetype setup¶

cytetype setup [--api-url URL] [--force]

Signs you in with your browser and saves a personal API key on this computer.

What the command does:

1. If a key for this server is already saved and you did not pass --force, it checks the key with the server. If the key is valid, it prints CyteType is already configured for <email>. and your dashboard link, and opens no browser. If the server rejects the key as invalid or disabled, the command stops with the server’s message followed by “Run cytetype setup --force to re-authenticate with a new key”.

2. Otherwise it starts a temporary listener on 127.0.0.1, on a free port, and opens the CyteType sign-in page in your default browser. It also prints the same link, so you can copy it if no browser opens.

3. In the browser, sign in with the one-time code sent to your email (if that browser is not signed in yet), then select Authorize CLI.

4. The browser returns to the listener. The command exchanges a short-lived code for your API key, saves it and prints API key saved for <email> in <path>. and your dashboard link. The browser shows “CyteType setup is complete.” and moves on to the dashboard after a few seconds.

The command waits at most 5 minutes for you to finish in the browser. The API key never appears in the browser’s address bar or in the terminal.

The key you get is your personal key named “CyteType CLI”. If that key exists and is active, setup returns the same key, so every computer you sign in to this way shares it. If you disabled it, the next setup --force creates a new one.

Example output (the banner is left out):

Opening CyteType sign-in in your browser.
If it does not open automatically, use this URL:

<sign-in link>

API key saved for you@university.edu in /home/you/.config/cytetype/credentials.json.
Dashboard:  https://cytetype.nygen.io/dashboard

The browser is opened with open on macOS, xdg-open on Linux and the Windows default browser under WSL. If none is available, the command prints Was not able to launch web browser and keeps waiting: copy the printed link into a browser on the same computer.

cytetype get-key¶

Another name for cytetype setup, with the same options and behavior.

cytetype login¶

cytetype login [--api-url URL]

Saves an API key that you already have, for example one created on the API keys page of the dashboard. The command asks for the key at a hidden API key: prompt, checks it with the server, and saves it only if the server accepts it. If the check fails, nothing is saved and any key saved earlier stays in place. Personal keys (starting with cyt_p_) and organization keys (starting with cyt_) both work.

Output on success:

Signed in as you@university.edu.
API key saved in /home/you/.config/cytetype/credentials.json.
Dashboard:  https://cytetype.nygen.io/dashboard

The prompt reads the key from your terminal. A notebook has no terminal to type into, so open one (in JupyterLab: File, New, Terminal) or pass the key to run() as auth_token instead (see Sign in and API keys).

cytetype logout¶

cytetype logout

Deletes the saved credentials file on this computer and prints Local API key removed. Revoke it from the dashboard if needed., or No local CyteType API key was found. if there was none. The key itself keeps working wherever else it is saved or used. To stop it from working everywhere, disable it in the dashboard.

cytetype dashboard¶

cytetype dashboard

Prints the dashboard address of the server you are signed in to and opens it in your browser. Without a saved sign-in, it opens https://cytetype.nygen.io/dashboard. The command takes no options and does not use CYTETYPE_API_URL.

cytetype view¶

cytetype view JOB_ID

Prints and opens the report of a job. The link goes through the sign-in page of the server you are signed in to (without a saved sign-in, https://cytetype.nygen.io), so you may be asked to sign in first. If the browser is already signed in, you go straight to the report. The command does not check that the job exists or that you may open it; the report page does that. It takes no --api-url option and does not use CYTETYPE_API_URL.

cytetype --version and --help¶

cytetype --version prints cytetype <version>, for example cytetype 0.21.0. cytetype --help (or -h) lists the commands, and cytetype COMMAND --help describes one command.

cytetyper (R)¶

Install the launcher¶

library(CyteTypeR)
InstallCyteTypeRCli()

InstallCyteTypeRCli() copies a launcher named cytetyper (cytetyper.cmd on Windows) into a folder, prints Installed <path>. and returns the path invisibly.

Other errors you may see:

The launcher starts R with Rscript --vanilla, which skips your .Rprofile and .Renviron files. CyteTypeR must therefore be installed in a library that R finds without them (not only in a project library such as renv), and CYTETYPE_API_URL must be set in the shell, not in .Renviron. See Installation for the other requirements.

Usage¶

cytetyper setup [--api-url URL] [--force]
cytetyper get-key [--api-url URL] [--force]
cytetyper login [--api-url URL]
cytetyper logout
cytetyper dashboard
cytetyper view JOB_ID [--api-url URL]
cytetyper --version

cytetyper without arguments, cytetyper -h and cytetyper --help print this help; cytetyper COMMAND --help describes one command. Give options as --api-url URL or --api-url=URL, each at most once.

Each command calls the R function shown in Commands at a glance, so it behaves like the Python command of the same name described above. The differences:

• cytetyper login reads the key from standard input. Type or paste it at the API key: prompt (on Linux and macOS, what you type is not shown), or pipe it in, for example printf '%s\n' "$CYTETYPE_API_TOKEN" | cytetyper login. An empty key stops the command with Error: API key is required.

• cytetyper view accepts --api-url. Without it, it uses the server you are signed in to, then CYTETYPE_API_URL, then https://cytetype.nygen.io.

• cytetyper --version prints cytetyper <version>, for example cytetyper 0.6.0.

• Usage errors (an unknown command or option, a missing JOB_ID) end with exit status 1, not 2.

• If setup cannot open a browser, R warns Could not launch a web browser. instead of printing Was not able to launch web browser. Copy the printed link in either case.

The R functions¶

Because LoginCyteTypeR() accepts the key as an argument, it is useful on machines where a prompt is inconvenient:

LoginCyteTypeR(api_token = Sys.getenv("CYTETYPE_API_TOKEN"))

The variable name is your choice: CyteTypeR does not read it on its own.

Server URL and CYTETYPE_API_URL¶

The default server is https://cytetype.nygen.io. You only need another address if you were given one, for example for a development server.

setup, get-key and login (and the R functions SetupCyteTypeR() and LoginCyteTypeR()) choose the server in this order:

1. --api-url (R: the api_url argument);

2. the CYTETYPE_API_URL environment variable;

3. https://cytetype.nygen.io.

The same variable sets the default server of CyteType() in Python and of the CyteTypeR functions. In an R session, when the variable is not set, the R option cytetype.default.api.url is used if you set it.

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

Both clients accept only a server origin:

• a scheme, a host name and an optional port, with no path, query string, fragment or user name (a trailing / is removed);

• HTTPS, except for http://localhost and http://127.0.0.1.

Anything else fails with API URL must be an HTTP or HTTPS server origin or Non-local API URLs must use HTTPS. In Python, a CYTETYPE_API_URL that is set but empty is also rejected; unset it instead (unset CYTETYPE_API_URL).

The saved sign-in belongs to one server. Signing in to another server replaces it, and the clients do not send a key saved for one server to another.

Saved credentials¶

setup, get-key and login write a file named credentials.json: in $XDG_CONFIG_HOME/cytetype/ when that variable is set, otherwise in %APPDATA%\cytetype\ on Windows and in ~/.config/cytetype/ on Linux and macOS. Where the key is saved describes how the file is protected.

• There is one file per user account on the computer. The Python and R clients and both command-line tools share it.

• It holds the sign-in for one server: the API key as plain text, the server and dashboard addresses, your email, and your user and key IDs. Do not share it, commit it or copy it into notebooks.

• No environment variable holds the API key itself. In scripts and CI, pass the key as auth_token to run() or CyteTypeR() (see Sign in and API keys).

Environment variables¶

Output and exit codes¶

cytetype prints results to standard output and errors to standard error, as Error: <message>. cytetyper also prints errors as Error: <message>, and prints its other messages, such as links and the signed-in email, to standard error too.

Messages you may see, and what to do:

For errors that appear while you run jobs, see Errors and error codes.