Account setup#

Install on Linux or macOS first. Use omagma when the verified executable is on PATH. Bundle commands below use zig-out/bin/omagma relative to its extracted omagma/ directory; Homebrew users replace that prefix with omagma. Zig is not required for release installation.

Recommended: ask an agent to guide you. Point your coding agent at this repository and use a setup prompt. It can walk you through Google Console one step at a time, use your feedback to identify the current screen, prepare private files and open each account's consent in the correct Chrome profile. You complete the Google registration and approval clicks. Tell it whether you want read-only browsing or full TUI/CLI access. The steps below also work for manual setup.

On a new Mac setup, also choose Interactive or Agent-enabled. Interactive defaults to native Keychain for a local unlocked terminal; Agent-enabled uses the same executable with private owner-only, unencrypted token files. An existing explicit choice is preserved during repairs.

Choose the access you want before connecting an account:

The full scope URLs and Console steps are in full TUI/CLI permissions. For a fresh terminal-only installation, start with that section and one registration. If you already use a bar/read-only registration in oauthClientFile, keep it and use a different registration for broader terminal permissions. TUI and CLI share the terminal grant; each configured account authorizes separately.

If a private config already exists, edit it instead of copying the example over it. For a new configuration:

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/omagma"
chmod 700 "${XDG_CONFIG_HOME:-$HOME/.config}/omagma"
cp examples/config.json "${XDG_CONFIG_HOME:-$HOME/.config}/omagma/config.json"
chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/omagma/config.json"

If XDG_CONFIG_HOME is set, the default location is $XDG_CONFIG_HOME/omagma/config.json instead. You can always pass --config explicitly. Keep private configuration and OAuth downloads outside the repository.

Read-only Google OAuth registration#

Register Omagma in your Google project, then approve access for each mail account. Google Console lists these registrations under Clients.

1. Create a Google Cloud project and enable the Gmail API.
2. Configure the Google Auth consent screen. Use an External audience for accounts from different Workspace organizations; an Internal application is limited to its organization. Add intended accounts as test users while in Testing. Workspace administrators can restrict access. Google’s verification guidance.
3. Under Data Access, add https://www.googleapis.com/auth/gmail.readonly for the bar. For full terminal access, also add the scopes in full TUI/CLI permissions; keep the bar's readonly entry.
4. In Google Auth Platform → Clients → Create client, select Application type → Desktop app, give the registration a name, and click Create. Download its JSON to a private local location, with file mode 0600. Omagma uses a browser consent flow, PKCE and a loopback callback. Google’s installed-app documentation.
5. Set oauthClientFile to the file’s absolute path in your configuration.

The requested gmail.readonly scope is a restricted Gmail scope. Although the bar fetches only a bounded Inbox page and metadata, the permission itself allows broader mailbox reading. Terminal read-only commands can use that grant to fetch full bodies, threads and attachments within their separate limits. Gmail scope definitions.

External applications in Testing receive refresh tokens that expire after seven days for these Gmail/contact permissions. This applies to both the bar and terminal grants: reconnect an expired bar grant with auth, and an expired terminal grant with terminal-auth authorize using its terminal registration and complete capability set. Production removes that Testing-specific expiry; tokens can still expire or be revoked for other reasons. Public availability and verification are separate decisions governed by Google’s requirements. Token expiration, distribution.

Configuration#

{
  "oauthClientFile": "/absolute/private/path/google-registration.json",
  "chromeUserData": "",
  "refreshIntervalSeconds": 0,
  "accounts": [
    {"address": "personal@example.com", "profile": "Profile 1", "enabled": true, "required": true},
    {"address": "work@example.com", "profile": "Profile 2", "enabled": true, "required": true},
    {"address": "optional@example.com", "profile": "Profile 3", "enabled": false, "required": false}
  ]
}

For a terminal-only configuration, omit oauthClientFile (or leave it empty) and pass the terminal registration JSON with --client-file when authorizing. Do not set it to your terminal file while retaining a read-only bar grant.

Replace the fictional addresses and profile directories. One to three accounts are supported; addresses and profiles must be distinct. For a first-account setup, configure only that one account or disable the other slots. required controls the initial selection among enabled accounts. Disabled accounts remain visible as unavailable if included in the configuration.

Open chrome://version in each intended Chrome profile and use the final directory name from Profile Path, such as Profile 1. This is the directory name, not Chrome’s displayed profile label. The Default profile is rejected to avoid ambiguous routing. chromeUserData may be an absolute existing Chrome data directory; an empty value uses the standard Google Chrome directory. When opening mail, meeting links or previews, omagma validates the existing profile and passes its configured data directory and profile to Chrome.

Omitting chrome uses /usr/bin/google-chrome-stable on Linux and /Applications/Google Chrome.app/Contents/MacOS/Google Chrome on macOS. The default Chrome data directory is $HOME/.config/google-chrome on Linux or $HOME/Library/Application Support/Google/Chrome on Mac. Override these only when your existing installation differs.

JSON paths must be absolute, expanded paths; ~ and $HOME are not expanded inside JSON. refreshIntervalSeconds must be a JSON integer: 0 disables background refresh, and 60..86400 enables it. Use 300 for five minutes. Refresh behavior.

Each account may also set "senderName": "Alex Example" and "signature": "Alex\nExample team". Sender names reject ASCII control characters. Signatures are plain text; newlines and tabs are allowed, while other ASCII controls are rejected.

Credential storage#

credentialStore is "keyring" by default: Secret Service on Linux and the current default user Keychain on macOS. The keyring must be available and unlocked in the context running Omagma. To authorize directly into the file store, add "credentialStore": "file" and set credentialDirectory to an absolute canonical private directory before consent. The directory uses mode 0700, token files use 0600, and tokens are not encrypted at rest. Keep them outside Git and shared folders. The agent sandbox still needs the selected file permissions and Google network access. Authorization/migration may create the leaf directory and account subdirectories when ancestors are safe; unsafe existing owners, modes, ACLs or symlinks are refused.

Inspect the selected store with omagma credentials status --json, using your usual --config and custom --grant-file when applicable. For existing grants, use credential migration from a context able to read the source. Migration needs no new Google consent, verifies private destination copies before switching the config, and retains source copies. Restart open sessions after switching stores.

Connect each enabled account#

zig-out/bin/omagma auth --account personal@example.com --config "${XDG_CONFIG_HOME:-$HOME/.config}/omagma/config.json"

Complete Google consent in the opened Chrome profile within 180 seconds. omagma checks the returned Gmail identity against the configured address before storing a refresh token in the selected credential store. Repeat the command for each other enabled address. With the default keyring store, the platform keyring must be available and unlocked.

For the bar, use the live entry in installation and refresh the account after connecting. If you previously chose its optional demo mode, set fixtures to false. If consent expires or access is revoked, run auth again for that account. There is currently no in-dropdown Connect action. Verify that Open inbox and message links reach the intended account in the intended profile.

Full TUI/CLI permissions#

Full current terminal functionality uses these two Google scopes:

gmail.modify includes the needed mail-read/send access; contacts includes contact reads and writes. Omagma still checks each local capability separately. Invitation replies are RSVP emails, so no Calendar API or Calendar scope is needed. Omagma currently manages local drafts, assigns/removes existing labels, and creates/edits contacts; it has no permanent mail deletion, contact deletion, label creation/renaming/deletion or calendar views. Google's Gmail scopes, contact write scope.

The permission itself also covers creating, editing and deleting Gmail label definitions. Omagma currently applies/removes existing labels; those label management operations still need implementation. They do not require an extra scope. Create labels, edit labels, delete labels.

Fresh terminal-only installation#

On Mac, and on Linux without the bar, one Google OAuth registration is enough:

1. Create or reuse a Google Cloud project and enable Gmail API and People API.
2. Configure the Google Auth consent screen. Use External for accounts from different Workspace organizations and add intended accounts as test users while in Testing.
3. In Data access, add the two full scope URLs above.
4. In Clients → Create client, select Application type → Desktop app, name it Omagma Terminal, create it and download the JSON to a private local file with mode 0600.
5. Configure your requested accounts, existing Chrome profiles and chosen credential store before consent. Omit oauthClientFile or leave it empty; there is no read-only bar registration to preserve.
6. Run the six-capability authorization command below with --client-file, then check status and real mail/contacts with reads. Homebrew users invoke omagma instead of zig-out/bin/omagma.

Do not create or authorize a bar registration solely to use the TUI or CLI. If you later add a Linux bar, give it its own read-only registration.

Existing working bar installation#

Preserve the bar’s current registration, grant and private configuration:

1. Select the same project in Google Cloud Console. In APIs & services → Library, enable People API. After enabling it, the API/service details page shows Status: Enabled and a Disable API action. Gmail API should already be enabled.
2. In Google Auth Platform → Data access → Add or remove scopes, use Manually add scopes to paste the two full scope URLs above, one per line. Click Add to table, then Update, and Save if shown. Keep the existing gmail.readonly entry for the bar.
3. In Audience, keep your existing audience and publishing choice. If using External Testing, ensure this account is a test user. The existing project and branding can serve both registrations.
4. In Clients → Create client, choose Application type → Desktop app, name it Omagma Terminal, click Create, then Download JSON. You can dismiss the dialog after the file has downloaded. This Console option registers the locally installed program. Create a new entry with a different Client ID from the bar's registration; renaming or copying its JSON does not create another registration.
5. Keep the new JSON in a private directory outside the repository, with file mode 0600; a friendly filename such as terminal-registration.json is useful. Give your agent its local path rather than pasting its contents. Keep both registration files. oauthClientFile in the account config continues to point at the bar's original registration JSON. Pass the terminal file with --client-file below.
6. Authorize one configured account with all six local capabilities:

zig-out/bin/omagma terminal-auth authorize --account personal@example.com \
  --config "${XDG_CONFIG_HOME:-$HOME/.config}/omagma/config.json" \
  --client-file /absolute/private/path/terminal-registration.json \
  --capabilities mail-read,mail-send,mail-modify,contacts-read,contacts-write,calendar-rsvp

The browser opens in that account's configured Chrome profile. Complete consent within three minutes. Select the exact account and approve both Gmail and contacts access, using Select all if offered. Adding Console scopes alone does not upgrade an existing token. Once the callback page reports authorization received, you can close that tab; wait for the command to finish successfully, then inspect the grant:

zig-out/bin/omagma terminal-auth status --account personal@example.com \
  --config "${XDG_CONFIG_HOME:-$HOME/.config}/omagma/config.json"
zig-out/bin/omagma tui --account personal@example.com \
  --config "${XDG_CONFIG_HOME:-$HOME/.config}/omagma/config.json"

Restart an already open TUI after its grant changes. The CLI now uses the same permissions. Repeat authorization for each additional configured account one at a time, using the same terminal registration JSON. Wait for successful CLI completion before opening the next account's consent; credentials remain separate per account. An agent can confirm the recorded capabilities and read mail/contacts to check access; setup does not require sending a test message or changing your data. For Agent-enabled setup, verify live CLI subprocess reads from the intended agent context rather than relying on an interactive TUI. Tokens live in the selected credential store. The private grant registry defaults to ${XDG_CONFIG_HOME:-$HOME/.config}/omagma/terminal-grants.json; if you choose a custom --grant-file, use it consistently for consent, status, TUI and CLI.

For narrower access, use the smaller permission sets. When changing capabilities, request the complete desired set in a new consent flow. Read-only bar credentials remain available for mail reading. See terminal workflows and the CLI contract for using the connected account. Console navigation follows Google's consent setup and Google OAuth registration instructions.

Smaller permission sets#

mail-read is required for a terminal grant. Choose the other local capabilities for the features you intend to use:

For terminal-only setup, use its one terminal Google OAuth registration. Alongside an existing bar/read-only registration, any set beyond mail-read alone uses a different terminal registration. For read-only browsing, the existing bar grant is sufficient; if authorizing an explicit mail-read terminal grant, --client-file may be omitted to use the configured oauthClientFile.

Scope names above use the prefix https://www.googleapis.com/auth/. Add the full URLs for your chosen smaller set under the project's Data access, including gmail.send or contacts.readonly when the table requests them. The full-access setup uses gmail.modify and contacts instead. Full Google scope coverage does not automatically enable an omitted local capability. The complete six-capability set above avoids that mismatch for full TUI/CLI use. Gmail settings aliases are read through the mail grant; changing Google settings is not part of the current terminal interface.

Background cache with a terminal-only installation#

The optional Linux terminal cache timer deliberately uses the read-only bar grant. To enable that timer, configure the bar's read-only registration and run auth for each requested account even if you never install the bar widget. The full terminal grant alone does not authorize automatic cache fetching. Both credentials can coexist in the same private account config and separate credential namespaces. This optional background setup is not a prerequisite for interactive terminal use. Mac installation does not install the supplied Linux systemd units or create a Mac background service.

Reconnect or change permissions#

For the bar, repeat its auth command. For the terminal, repeat terminal-auth authorize with the terminal registration JSON and the complete capability set you want to retain, then run terminal-auth status and restart an already open TUI. Google consent replaces the requested set rather than incrementally adding one capability.

If Google reports that an API is disabled, enable Gmail API or People API in the registration JSON's project as appropriate. SeparateTerminalClientRequired means the same Google OAuth registration was used for the bar and terminal; create a new registration in the Console rather than copying the file. An External Testing account must be listed under Audience → Test users. Report any actual Workspace policy block before changing permissions or project settings.

Optional Google Cloud CLI#

If you already use gcloud, it can enable the required APIs in an existing project. This is optional; the Console Library steps above are sufficient. Use an account allowed to enable services on that project:

gcloud auth login admin@example.com --no-activate
gcloud services enable gmail.googleapis.com people.googleapis.com \
  --project=YOUR_PROJECT_ID --account=admin@example.com

This authorizes Google Cloud administration, not Omagma's Gmail access. Configure the Google Auth Platform Data access scopes, test users and separate Google OAuth registration through the Console, then use Omagma's terminal-auth authorize for per-account mail/contact consent. gcloud iam oauth-clients and gcloud iap oauth-clients manage other registration types and are not substitutes for the Google OAuth registration used here. Cloud CLI installation, API enablement command, Google OAuth registration setup.