Command-line tools

Choosing how to sign in

In the first two, you sign in at the photo service and approve photos-cli, so the tool receives tokens limited to what you approved. photos-cli is installed by everyone who downloads it, so it is a public client with no secret, and both flows rely on the protections public clients use, such as PKCE in the authorization code flow.

Signing in with a browser

On your laptop, signing in runs the authorization code flow with PKCE, as any desktop application would. All domains, tokens, and keys in these examples are fictional.

$ photos-cli login
Opening your browser to sign in at auth.photos.example.
If it does not open, visit this address:
https://auth.photos.example/authorize?response_type=code&client_id=photos-cli&...
Waiting for you to finish signing in...
Signed in. Tokens saved in the system credential store.

The address is shortened here for display. Before opening the browser, the tool asked the operating system for a free port and started listening on it at 127.0.0.1, the loopback address that only programs on the same machine can reach. Its authorization request used http://127.0.0.1:53682/oauth/callback as the redirect URI. As the Redirect URIs and client metadata lesson explained, the photo service matches loopback addresses exactly except for the port. When you approve, the browser delivers the code to the tool's temporary listener, which shows a short "You can close this window" page, stops listening, and exchanges the code with its verifier.

The listener's details matter. It binds to the loopback interface only, so no other machine on the network can send it a response. It uses the literal address 127.0.0.1 rather than the name localhost, which a misconfigured machine could resolve somewhere unexpected. And it listens only for the length of the sign-in. Another program on the same machine could still try to grab the code, which is one more reason the exchange depends on the verifier.

On a remote server there is no browser to open, and the tool switches to the device authorization grant, which the Device authorization lesson followed with a photo frame:

$ photos-cli login --device
On a device with a browser, open https://photos.example/device
and enter the code PXGH-KQRT.
Waiting for approval...
Signed in.

You approve on your laptop or phone while the tool polls. The frame's warning applies here too: only enter a code that you have just seen printed by a tool you started yourself.

Credentials without a sign-in flow

Many services also let you create a personal access token or API key in your account settings and paste it into a tool. This is not OAuth. There is no authorization request and no consent screen for a particular client, just a credential you made for yourself. These tokens are popular because they are simple: they work in any script, on any machine, with no browser.

The simplicity has costs. Personal access tokens often last until someone remembers to delete them, carry whatever access was selected when they were created, and end up in scripts, configuration files, and chat messages. The service cannot tell which tool is using one, and nothing refreshes or rotates it. Services that offer them reduce the risk with expiry dates, narrow scopes chosen at creation, a page where you can review and revoke your tokens, and a recognizable prefix in each token value, which lets code-hosting services spot one that was committed by mistake and report it.

Automation deserves separate thought. Running a scheduled job with your own sign-in gives the job your authority for as long as its refresh token lasts. When the work belongs to an organization rather than to one person, such as archiving Lantern Studio's shared albums every night, the job should have its own client registration and use the client credentials grant, keeping its credential in the scheduler's secrets store. Its access is then defined for the job and can be reviewed or removed without touching anyone's personal account. That grant is only for software acting as itself. A tool acting for you should get its access from your approval.

Storing tokens on the machine

After you sign in, photos-cli holds a refresh token that keeps it working for weeks. Where the tool keeps that token decides who else can use it.

The best place is the operating system's credential store: the Keychain on macOS, Credential Manager on Windows, or a Secret Service keyring on Linux desktops. These stores keep secrets encrypted, release them to programs running as your account, and on some systems ask before doing so. Servers often have no such store, so the fallback is a file readable only by your account, such as ~/.config/photos-cli/credentials.json with permissions that exclude every other user. That stops other people on the machine, but not other programs running as you, and the file can travel into backups or a copied home directory.

Environment variables are convenient for automation, and they leak in their own ways. Every program the tool starts inherits them, and debugging output, crash reports, and build logs sometimes print the whole environment. Build systems usually mask known secret values in their logs, but a token printed in a slightly different form, encoded or split across lines, can slip past the mask.

Tokens also leak through the way commands are typed. A token given as an argument, as in photos-cli upload --token demo-cli-token-1, is saved in your shell history and, while the command runs, appears in the process list that other users of the same machine can often see. photos-cli instead reads a token from a prompt, from standard input, or from a file, which keeps it out of both.

Signing out finishes the job. photos-cli logout revokes the refresh token at the photo service's revocation endpoint, then deletes the stored tokens, so any copy of the refresh token that escaped earlier, into a backup or a log, stops working too.