Targets and configuration
A target is the Modem app deployment a command contacts. Live/Sandbox is a project or credential mode within that deployment, not a separate server target.
Selection order
The CLI chooses its app target in this order:
--modem-app-url, orPRETERNATURAL_MODEM_APP_BACKEND_URL.--environment, orPRETERNATURAL_MODEM_ENV.- The stored default target.
- Production.
Named environments are production, development and local. Production and development currently share the app origin; local uses the Localnet service name. Do not assume --environment development means an isolated Sandbox workspace.
modem-cli --environment local auth login --web
modem-cli --environment local projects list
modem-cli --environment production auth login --web
modem-cli auth switchThe first successful login sets the default if none exists. Logging into another target does not necessarily change the default; auth switch does. With an explicit target it selects that stored target; without one it offers the stored targets interactively.
Custom deployments
modem-cli --modem-app-url "$MODEM_APP_URL" \
--gateway-base-url "$MODEM_GATEWAY_URL" auth login --webRecord the matching gateway when logging into a custom app URL. App and gateway are distinct endpoints; model lookup, completions and logs need the gateway. An app URL outside the named presets does not imply a gateway URL. A later --gateway-base-url override takes precedence over the stored value.
All commands accept --config-path to select another credential file. This also supports separate automation profiles without copying secrets between unrelated targets.
Stored credentials
The default file is ~/.config/preternatural/modem-cli-config.yaml, with owner-only permissions. Entries are keyed by canonical app URL and record the key’s ID, origin and optional gateway. A key is selected for that app URL, rather than blindly reused for every deployment.
PRETERNATURAL_MODEM_ADMIN_API_KEY overrides the stored key for the selected target and is never saved. Selecting the target correctly remains your responsibility when using this environment variable.
A malformed config produces a recovery message instead of silently ignoring its contents. auth logout --all can remove it without reading the old schema. Reauthenticate and restore target defaults afterward.
Project mode
modem-cli projects create --name 'Test app' --mode sandboxOmitting --mode selects the key’s only allowed mode, or Live when it allows both. Changing the deployment target does not convert an existing project’s mode. See Sandbox mode.
An unreachable local target, 502, or a plain non-API 404 may mean the local app or Localnet service is not running. Use the running service’s discovered URL or correct target options before investigating credentials.