Authentication

The CLI signs in two ways: through your browser, or with a personal API key. The browser is the simplest on your own machine; the key suits CI and servers.

Sign in with your browser

auth:login opens Sofia in your browser. You approve the access, and the CLI receives it on a local address (http://127.0.0.1:<port>/callback). It is the OAuth2 authorization code flow with PKCE; there is no key to copy.

sofia auth:login

• --scopes "<s1 s2>": the scopes to ask for. By default, all the resource scopes plus offline_access.
• --no-browser: print the address instead of opening it, for a machine without a browser.

sofia auth:login --scopes "posts:read posts:write offline_access"
sofia auth:login --no-browser

Where credentials are stored

After auth:login, the CLI keeps your session in ~/.sofia/credentials.json (folder 0700, file 0600). An expired token is refreshed on its own and the file is rewritten.

{
  "apiUrl": "https://api.sofia-post.com",
  "clientId": "…",
  "accessToken": "…",
  "refreshToken": "…",
  "expiresAt": "…",
  "scope": "…"
}

Check and sign out

auth:status shows the account the CLI acts for. auth:logout deletes the credentials file.

sofia auth:status
sofia auth:logout

auth:logout only forgets the credentials on this machine: Sofia API has no revocation endpoint, so the access stays valid until you revoke it in Sofia under Settings › Connected apps.

Use a personal API key

Create a key in Sofia under Settings › API › Personal access, then export it as SOFIA_API_KEY. No auth:login needed: it is the way to go for CI and servers. More on keys in Authentication.

export SOFIA_API_KEY="sk_live_…"
sofia establishments:list

Which one wins

The browser credentials come before SOFIA_API_KEY. To use the key on a machine where you signed in, run sofia auth:logout first.

Environment variables

Ready to publish? Go to posts.