ts login

Sign in to the targeted Turbo Server, through the server's sign-in page in a browser, and keep the sign-in for later commands. A script or CI job authenticates as a registered client instead, with --client-id and --client-secret.

Usage

ts login [--device-code]
ts login --client-id=ID --client-secret=SECRET
ts --server=<url> login [--device-code]

Description

ts login opens the server's sign-in page in your browser, where you sign in through whichever identity providers the page offers. The browser hands the result back to ts on a port on this machine, and ts prints who you are signed in as. If no browser can be opened, ts prints the page's address for you to open yourself.

Where a browser would open in front of nobody, ts prints a code instead: open the page it names on any device, sign in, and enter the code. ts does this on its own when its output is not a terminal, inside an SSH session, and on Linux with no display. --device-code asks for it anywhere else. The code expires after ten minutes.

When you are already signed in to the server, ts login at a terminal says who and since when, and signs nothing in. Run ts logout first to sign in as someone else.

Choosing the Server

ts login signs in to the server the invocation targets: --server, then TSSERVER, then the default server. ts login --server=<url> makes <url> the default server when there is none, so the commands after it need no flag. When a different default is already set, it stays, and ts login says how to change it with ts config --server=<url>; a script that signs in to several servers keeps sending its unflagged commands to the same one. Sign-ins are kept per server, so signing in to a second server leaves the first signed in.

Signing In as a Client

--client-id and --client-secret, always together, authenticate as a client registered with ts client rather than as a person. ts prints Authenticated as <client-id>, and later commands act as the client's service account. ts does not store the secret. It keeps only the access token it receives, with nothing to renew it, so once that token expires the next command asks you to sign in again.

For an unattended job, set TSCLIENTID and TSCLIENTSECRET instead of signing in: every command then exchanges them for a fresh token, and nothing is stored. TSACCESSTOKEN supplies an access token directly, for one command or one shell. Either takes precedence over a stored sign-in.

What Is Stored

A person's sign-in keeps an access token and a refresh token. Access tokens last five minutes, and ts renews them as it goes; a sign-in left unused for 30 days ends. When the server refuses a renewal, because the session ended or was revoked, the command asks you to run ts login again. The tokens are kept in credentials.json, readable only by you, in %LOCALAPPDATA%\Turbo Server\cli on Windows and $XDG_CONFIG_HOME/turbo-server (usually ~/.config/turbo-server) elsewhere.

ts login takes no username or password. A script that passes them is refused with exit -4. On the server itself, ts --local needs no sign-in at all.

Options

Flag	Description	Default/Values	Notes
--device-code	Print a code to enter on another device instead of opening a browser.		ts already does this with no terminal, over SSH, and on Linux with no display.
--client-id	Authenticate as a registered client instead of a person.	Client ID	Requires --client-secret.
--client-secret	That client's secret.		Lands in shell history; see the examples.

Examples

# Sign in to a server and make it the default
ts login --server=https://turbo.example.net

# Sign in to the default server
ts login

# On a machine with no browser, or one you reach over SSH
ts login --device-code

# Sign in to a second server; the default stays where it was
ts --server=https://staging.example.net login

# A CI job, authenticated as a registered client for every command
export TSCLIENTID=ci-deploy
export TSCLIENTSECRET="$CI_DEPLOY_SECRET"
ts workspaces

# A secret typed literally is recorded in shell history and visible in the
# process list. Read it from an environment variable instead.
ts login --client-id=ci-deploy --client-secret=hunter2

Output

Opening https://turbo.example.net/api/v1/oauth/authorize in your browser.
Waiting for sign-in.
Signed in as alice
Default server set to https://turbo.example.net

With a code:

Open this page on another device:

    https://turbo.example.net/api/v1/oauth/verify?user_code=BXKQ-TRMV

and enter the code  BXKQ-TRMV

Waiting for approval.
Signed in as alice

With --format=json, the result carries a user object with the server and login name, or a client object with the server and client ID.

Exit Codes

0 on success, including when you are already signed in. -1 when no server is configured or named, or when --client-id or --client-secret comes without the other. -3 when the server cannot be reached. -4 when the sign-in is denied, fails or expires, when the server refuses the client's credentials, when the server has no sign-in service, and when a username, password or API key is given.

Related Commands

• ts logout — Sign out, and optionally end the session on the server.
• ts config — Show or change the default server.
• ts client — Register the client a script signs in as.
• ts status — Check what ts is pointed at and whether it is healthy.