Authenticate

Use this guide when you need to pair gsds with your community for the first time, refresh an expired session, confirm which tenant you are paired with, or sign out of a shared machine.

Pair a session

Get a pairing code from your community:

1. In the community admin, open Integrations from the sidebar.
2. Under the Developer Studio heading, choose CLI Access.
3. Copy the pairing code from that page.

Then, in your terminal, redeem it:

gsds login PAIRING-CODE-FROM-COMMUNITY

Pairing codes have a 1-minute time-to-live, so open CLI Access with your terminal already open. If the code expires before you paste it, refresh CLI Access and try again.

On success, gsds stores a tenant-scoped session token that is valid for 8 hours.

Check the current session

gsds login --status

Reports which tenant the current session is bound to and whether it is still valid. Use this first whenever you see a 401 from gsds preview or gsds connector test.

gsds preview reports a missing session and an expired one differently — see Troubleshooting for what each message means.

Refresh an expired session

There is no refresh flow — when the 8-hour token expires, get a new pairing code from Integrations → Developer Studio → CLI Access and redeem it:

gsds login NEW-PAIRING-CODE

Log out

Clear the stored session:

gsds logout

Run this before handing a shared workstation to another developer, or when switching between tenants.

Use multiple tenants

Each community you pair with is a separate tenant. Logging into a second tenant does not replace your first session. Each gsds login keeps its own profile, keyed by tenant, and whichever one you just logged into becomes current — every other command uses the current profile automatically.

gsds profile              # list stored profiles, marks the current one and any needing a re-login
gsds profile use <name>   # switch which one is current

gsds profile marks a profile whose session has timed out (expired), and one whose stored credential is present but cannot be read back — corrupted, hand-edited, or restored from a backup — (unreadable). Markers combine, so the current profile can itself be expired and shows as (current, expired):

acme-en (current)
acme-eu (expired)
acme-sandbox (unreadable)

An expired profile stays stored and stays switchable — it is the name to log back in under, so nothing is dropped from the list.

gsds logout promotes another profile to current when one remains, preferring one that is neither expired nor unreadable, and tells you when the one it promoted still needs a new login.

Pass --profile <name> on gsds login, gsds preview, gsds logout, or gsds connector test when you want to name a profile explicitly — for example logging into the same tenant twice under different names — or target a profile other than the current one for a single command without switching it.

Use the same account as your community session

gsds preview registers its preview session against the account that redeemed the pairing code. The No-Code Builder then looks for a preview session belonging to the account you are signed in as, so the two have to be the same person.

A session paired under a different account on the same tenant — a colleague's login, or a second account of your own — is not visible to you in the builder, and your local widgets never appear there. gsds login --status reports which session is current.

Where the session is stored

gsds writes the session token to your OS keychain, one account per profile, with a file-based fallback when no keychain is available. See Project Files for the full storage rules and paths.

Commands that require a session

Command	Why it needs a session
gsds preview	Registers a preview session with your community so local widgets appear in the picker, for the account that paired it
gsds connector test	Runs against the paired tenant

Every other command works without a session.

Next steps

• Test a Connector against the paired tenant in Test Connectors
• Run gsds unattended in CI or from an AI agent with Automate with CI and AI
• Look up flags for the login commands in the Command reference