dolt login allows you to authenticate a dolt client against DoltHub or DoltLab. It usually works, but when it fails, this article will help you debug it.

What is dolt login?

dolt login is the built-in wizard to authenticate your dolt client against DoltHub or DoltLab.

On the command line, you type dolt login and hit enter.

$ dolt login
Credentials created successfully.
pub key: otb4s9ig4klcvjc57gbjrnopm4jb867oktladhrh3nnq1dkdruog
/Users/timsehn/.dolt/creds/esv3b02b0tjtsb4agfpmms9t6rk3k88iaqv3jcgt6n3jq.jwk
Attempting to automatically open the credentials page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
	https://dolthub.com/settings/credentials#otb4s9ig4klcvjc57gbjrnopm4jb867oktladhrh3nnq1dkdruog
Please associate your key with your account.
Checking remote server looking for key association.
Retrying in 3

A browser opens to the DoltHub credentials page with a new Public Key added in the "Add credential section". You add a Description, in this case "New Credential", and click "Add".

The command on your dolt command line client will then complete. Your dolt client is now logged into DoltHub.

Why dolt login?

If you need to write, i.e. dolt push, to any database on DoltHub or DoltLab, you need to dolt login. Write access is restricted to logged in clients.

If you want to read, i.e. dolt clone, dolt fetch, or dolt pull, from a private database on DoltHub or DoltLab, you need to dolt login as a user with read permissions to that private database.

What Does dolt login do?

dolt login is a convenience wrapper around the primitives provided by dolt creds. By default, dolt login creates a new credential, a public/private key pair, with dolt creds new. Then it makes a request to the DoltHub credentials page and attempts to register the newly created public key for the user currently logged into DoltHub. A new browser tab is opened and the dolt client polls to see if the credential is added. Once it is added, the dolt login command completes and the user is authenticated against DoltHub.

What about DoltLab?

DoltLab is a self-hosted version of DoltHub. You deploy your own DoltLab website and remote endpoint. To authenticate against DoltLab, dolt login requires you point it at the proper authorization endpoint and login URL by passing in --auth-endpoint and --login-url.

For instance, to dolt login to the demo DoltLab instance at https://doltlab.dolthub.com/, you run the following command:

$ dolt login --auth-endpoint doltlab.dolthub.com:50051  --login-url https://doltlab.dolthub.com/settings/credentials

The authorization endpoint is hosted on port 50051 of the host you set DoltLab up on by default. If you don't have the correct authorization endpoint, dolt login will just hang. But if you added the credential you should still be logged in. Just kill the dolt login command to get your shell back.

How does dolt login fail?

Speaking of failures. dolt login can fail in lots of ways, especially against DoltLab. Not specifying the proper DoltLab authorization endpoint as discussed above is one of them. DoltLab requires specifying the correct --auth-endpoint and --login-url for dolt login to work correctly.

We have also seen failures where somehow, the public keys DoltHub or DoltLab knows about are not being used by the dolt client on your machine. There's fairly sophisticated debugging equipment built into the dolt client. Let's show you how to use it.

Debugging dolt login

The easiest way to debug dolt login is to make sure you are authenticated using dolt creds check.

$ dolt creds check
Calling...
  Endpoint: doltremoteapi.dolthub.com:443
  Key: s5us7qiq5ckj657uslolkqef7gltal2l7hbh1neb8ffd5690e240

Success.
  User: timsehn
  Email: tim@dolthub.com

dolt creds check also takes an --endpoint option if you want to test against a DoltLab instance.

$ dolt creds check --endpoint doltlab.dolthub.com:50051
Calling...
  Endpoint: doltlab.dolthub.com:50051
  Key: fvh4i9t19erfdkuitju8q5kplse0g0o073drh301re6qmh2uo310

Success.
  User: timsehn
  Email: tim@dolthub.com

If you are not logged in, you need to dig a little deeper manually. First run dolt creds ls to see the available public keys on your machine. Your active credential has a * next to it. Right now, I have two on my machine, one for DoltHub and one for the DoltLab demo instance.

$ dolt creds ls
  s5us7qiq5ckj657uslolkqef7gltal2l7hbh1neb8ffd5690e240
* fvh4i9t19erfdkuitju8q5kplse0g0o073drh301re6qmh2uo310

Make sure the active credential matches on the DoltHub credentials page or your DoltLab instance's credentials page.

If the keys don't match, copy it and paste it into the "Public Key" field, add a description and click "Add". This should manually log you in.

If you have a key that is listed on DoltHub or DoltLab but not active on your client, you can switch to that key using dolt creds use <key>. Below, I am initially using my DoltLab public key. I switch to my DoltHub public key. I can then authenticate against DoltHub, but not DoltLab.

$ dolt creds ls
  s5us7qiq5ckj657uslolkqef7gltal2l7hbh1neb8ffd5690e240
* fvh4i9t19erfdkuitju8q5kplse0g0o073drh301re6qmh2uo310
$ dolt creds use s5us7qiq5ckj657uslolkqef7gltal2l7hbh1neb8ffd5690e240
$ dolt creds ls                                                      
* s5us7qiq5ckj657uslolkqef7gltal2l7hbh1neb8ffd5690e240
  fvh4i9t19erfdkuitju8q5kplse0g0o073drh301re6qmh2uo310
$ dolt creds check
Calling...
  Endpoint: doltremoteapi.dolthub.com:443
  Key: s5us7qiq5ckj657uslolkqef7gltal2l7hbh1neb8ffd5690e240

Success.
  User: timsehn
  Email: tim@dolthub.com
$ dolt creds check --endpoint doltlab.dolthub.com:50051              
Calling...
  Endpoint: doltlab.dolthub.com:50051
  Key: s5us7qiq5ckj657uslolkqef7gltal2l7hbh1neb8ffd5690e240
error: calling doltremoteapi with credentials.
cause: rpc error: code = Unauthenticated desc = jwt_token validation failed: key not found

If none of that works, it's time to hit us up on our Discord for live support. Something is really messed up!

Conclusion

It can be frustrating when you can't use DoltHub or DoltLab because you can't authenticate your dolt client with dolt login. Hopefully, this article helps you debug it without the Dolt team. If the article doesn't help, we provide live support via our Discord. We love supporting users there.