Skip to Content

Subscription commands

Subscription authentication is stored by Modem on its server. Native import copies a supported login into that storage; it does not make the relay depend on your laptop’s auth file.

Import

modem-cli subscription-signins import codex modem-cli subscription-signins import grok

Use --auth-file /path/to/auth.json for an explicit source. Codex import expects a ChatGPT subscription auth record, not an arbitrary Codex API-key identity. Its identity includes the user and workspace. Grok honors its native home/auth-path settings and validates the supported CLI OAuth issuer/client and principal; matching an email is not enough to identify a login.

The current source checkout also provides:

modem-cli subscription-signins import claude

Check that your installed CLI includes this command. Claude import honors CLAUDE_CONFIG_DIR and CLAUDE_SECURESTORAGE_CONFIG_DIR, selects the native macOS Keychain before file fallback, and accepts --auth-file and --account-file. Modem validates account/organization consistency; malformed explicit metadata is not treated as absent metadata.

Source auth files and Keychain entries are not edited. Providers can rotate single-use refresh tokens, so after Modem renews a copied login the native CLI may require sign-in again. A stale source file is not a reliable way to reconnect a rejected or uncertain renewable login. Use a freshly completed sign-in when reconnecting.

Duplicate choices

An existing account offers Update existing, Add another or Cancel in an interactive terminal. Update preserves the entry’s relay memberships and ordering. Add creates a distinct entry. Global --force selects Add another, including noninteractive duplicate imports; without it a noninteractive duplicate stops rather than silently replacing credentials.

Copies of one renewable login share renewal state and use the latest stored credentials. Removing one copy leaves the others usable; removing the last clears its stored credentials. Distinct entries for the same underlying account cannot both join one multiplexing group.

Create and configure a relay

modem-cli subscription-signins list modem-cli subscription-relays create \ --sign-in-id PRIMARY_SIGN_IN_ID FALLBACK_SIGN_IN_ID --name 'Development'

Use completed sign-ins from the same provider. One member is sufficient. The first is primary. The response includes the base URL, key and provider-specific clientSetup; follow those returned instructions instead of inventing a native client configuration.

The key is returned once. A returned credentialCommand may itself contain that key: treat the entire command as a secret. Later list and membership responses return metadata/previews, not another copy of the secret command. Subscription relay setup explains primary identity, quota/credits and continuation policies.

modem-cli subscription-relays members --relay-id RELAY_ID modem-cli subscription-relays set-members --relay-id RELAY_ID \ --sign-in-id NEW_PRIMARY_SIGN_IN_ID OTHER_SIGN_IN_ID

set-members reads the membership revision and atomically replaces the order. Concurrent changes reject the update; reload and decide the intended membership rather than overwriting unseen edits. Reordering preserves existing per-member options. The SDK membership API also exposes credit permission/timing; those are not separate CLI flags in this command.

subscription-relays revoke --relay-id RELAY_ID invalidates the link while keeping its subscriptions. A relay belongs to a project, rather than permanently belonging to whichever subscription is primary.

Inspect and diagnose

subscription-signins account --sign-in-id SIGN_IN_ID reads the provider account and may renew its token, so it needs write access. When reported, account.paidCredits describes credit availability; an absent field is unknown, not a zero balance.

subscription-signins chat --sign-in-id SIGN_IN_ID --prompt 'Hello' runs a coding agent on the server. It may take four minutes and requires the server’s native runtime prerequisites. This is a direct subscription diagnostic, not proof that a relay’s routing or limits work.

The current-source report-claude-quota command accepts status-line JSON on stdin with a stable --installation-id; --source agent-sdk accepts an Agent SDK result. It sends normalized quota windows and the installation ID, not a native login. Reporting quota does not import authentication, and an unavailable observation must not become a fabricated allowance.

Last updated on