@@ -5,9 +5,9 @@ authentication and identity only — `auth login` (OAuth or API key), `auth
 logout`, `auth status`, and `auth whoami`. Resource commands (contacts,
 sequences, inbox, …) come later.
 
-The CLI is one binary, `reply`. It targets **prod** by default; other backends
-are opt-in via user-defined profiles (see [Profiles](#profiles)). Credentials
-live in a per-user config dir with strict permissions.
+One binary, `reply`. It talks to Reply.io **prod** out of the box — no setup,
+no flags. (Profiles, below, are an optional extra for people who need more than
+one account.)
 
 ## Install
 
@@ -21,19 +21,21 @@ npm install -g @reply-team/reply-cli@next     # newest build off main (for teste
 npm install -g @reply-team/reply-cli@0.1.42   # a specific build
 ```
 
-Every commit on `main` is published under the `next` tag, so testers can install
-**any** build. Released builds are promoted to `latest`.
+Every commit on `main` is published under `next`; released builds are promoted
+to `latest`.
 
 ## Authentication
 
+For most people this is the whole story — no profiles, no config:
+
 ```bash
 # OAuth (authorization code + PKCE, loopback redirect — opens your browser)
 reply auth login
 
 # API key from stdin (kept out of shell history / argv)
 echo "$MY_API_KEY" | reply auth login --with-token
 
-# Active credential source, profile, user, and OAuth expiry (no secrets)
+# Active credential source, user, and OAuth expiry (no secrets)
 reply auth status
 
 # Validate the active credential against the API and print the principal
@@ -58,59 +60,79 @@ Resolved strictly in this order — first hit wins:
 The flag and env var are **ephemeral** — used for the current invocation only,
 never written to disk. There is no `.env` file lookup.
 
-## Profiles
+## Output & exit codes
+
+- Data goes to **stdout**; status and error messages go to **stderr**.
+- `--json` emits compact JSON; `--pretty` emits indented JSON.
+- On `--json`/`--pretty`, an error is a single machine-readable line:
+  `{"error":{"status":…,"code":…,"title":…,"detail":…,"hint":…}}`.
+
+Exit codes: `0` success · `1` API/runtime failure · `2` usage error.
 
-There is no built-in environment enum. A **profile** is a named backend bundle
-you define yourself. Which profile a command uses is resolved in this order:
+## Multiple accounts (optional — profiles)
+
+Skip this section unless you juggle more than one Reply.io account. A **profile**
+is a named credential slot; each keeps its own login, so you can switch between
+accounts without re-authenticating. Most people name profiles after the account
+email.
+
+```bash
+reply profile add alice@reply.io       # create (no URLs needed — inherits prod)
+reply profile add bob@reply.io
+reply profile use alice@reply.io       # make it current (persisted until changed)
+reply auth login                       # logs in as alice; stored under alice@reply.io
+
+reply profile use bob@reply.io && reply auth login   # separate login for bob
+
+reply profile list                     # * marks the current profile
+reply profile current                  # print the current profile name
+reply --profile bob@reply.io auth whoami   # one-off override, ignores current
+```
+
+Which profile a command uses is resolved as:
 
 ```
 --profile <name>  >  REPLY_PROFILE  >  current profile  >  default (prod)
 ```
 
-Define your own profiles in the config file:
+Credentials are keyed by profile name, so accounts never collide even though
+they all hit the same prod backend.
 
-```jsonc
-// ~/.config/reply/config.json   (Windows: %APPDATA%\reply\config.json)
-{
-  "profiles": {
-    "dev": {
-      "authority": "https://oauth.dev.replyapp.io",
-      "api_base":  "https://api.dev.reply.io/v3"
-    }
-  }
-}
-```
+### Advanced: a non-prod backend
 
-Use a profile per-command, or set a **current** profile so you don't repeat
-`--profile`:
+A profile can also point at a different backend by overriding the URLs; any
+field you omit is inherited from the embedded default (prod). This is mainly for
+internal testing against dev:
 
 ```bash
-reply --profile dev auth whoami   # one-off override
-
-reply profile use dev             # make dev current (persisted until changed)
-reply profile list                # list profiles; * marks the current one
-reply profile current             # print the current profile name
-reply auth whoami                 # now uses dev, no flag needed
+reply profile add dev \
+  --authority https://oauth.dev.replyapp.io \
+  --api-base  https://api.dev.reply.io/v3
+reply --profile dev auth login
 ```
 
-Each profile resolves to its own backend host, and credentials are stored
-per-host — so a `dev` session and your default (prod) session never collide.
-An unknown profile is a usage error.
+Or hand-edit the config file:
+
+```jsonc
+// ~/.config/reply/config.json   (Windows: %APPDATA%\reply\config.json)
+{ "profiles": { "dev": { "authority": "https://…", "api_base": "https://…/v3" } } }
+```
 
 ## Credential storage
 
 Credentials live in a JSON file in the per-user config dir, created with strict
-permissions (`0600` file inside a `0700` dir) — the same plaintext-file model as
-`gh`, `aws`, and `az`:
+permissions (`0600` file in a `0700` dir) — the gh/aws/az plaintext-file model:
 
-- Linux/macOS: `~/.config/reply/hosts.json` (honors `$XDG_CONFIG_HOME`)
-- Windows: `%APPDATA%\reply\hosts.json`
+- Linux/macOS: `~/.config/reply/credentials.json` (honors `$XDG_CONFIG_HOME`)
+- Windows: `%APPDATA%\reply\credentials.json`
+  (on Windows the strict perms are a no-op — it relies on your per-user
+  `%APPDATA%` ACLs, same as gh/aws/az)
 
-Each record is keyed by authority host and is either an OAuth record
-(access + refresh token + expiry) or an API-key record. An expired OAuth access
-token is refreshed automatically; if the refresh fails the record is cleared and
-you are asked to log in again. The store sits behind a `CredentialStore`
-interface — an OS-keychain backend is a planned opt-in addition.
+Records are keyed by profile name; each is either an OAuth record (access +
+refresh token + expiry) or an API-key record. Expired OAuth tokens refresh
+automatically; if refresh fails the record is cleared and you're asked to log in
+again. The store sits behind a `CredentialStore` interface — an OS-keychain
+backend is a planned opt-in addition.
 
 ## Configuration (env vars)
 
@@ -120,15 +142,6 @@ interface — an OS-keychain backend is a planned opt-in addition.
 | `REPLY_PROFILE` | Profile to use (same as `--profile`) |
 | `REPLY_CONFIG_DIR` | Override the per-user config directory |
 
-## Output & exit codes
-
-- Data goes to **stdout**; status and error messages go to **stderr**.
-- `--json` emits compact JSON; `--pretty` emits indented JSON.
-- On `--json`/`--pretty`, an error is a single machine-readable line:
-  `{"error":{"status":…,"code":…,"title":…,"detail":…,"hint":…}}`.
-
-Exit codes: `0` success · `1` API/runtime failure · `2` usage error.
-
 ## Development
 
 ```bash
@@ -140,7 +153,8 @@ npm link               # puts the real `reply` binary on your PATH to drive by h
 
 Tests never contact the network: `fetch` is stubbed and the OAuth loopback is
 exercised against a local `127.0.0.1` listener with an injected fake browser.
+CI runs the build + tests on Linux and Windows.
 
-**Releasing:** the `build` workflow publishes every `main` build to `@next`.
-When a build has been tested, the `release` workflow promotes that exact version
-to `@latest` (a dist-tag move — no rebuild) and tags the source commit.
+**Releasing:** the `build` workflow publishes every `main` build to `@next`;
+the `release` workflow promotes a tested version to `@latest` (a dist-tag move —
+no rebuild) and tags the source commit.
@@ -18,7 +18,7 @@ const fake_store = (seed: Record<string, Credential_record> = {})=>{
             delete map[h];
             return had;
         }),
-        hosts: vi.fn(async()=>Object.keys(map)),
+        keys: vi.fn(async()=>Object.keys(map)),
     };
     return {store, map};
 };
@@ -30,34 +30,34 @@ const fresh_oauth = (over: Partial<Oauth_record> = {}): Oauth_record=>({
 describe('auth/resolve — credential precedence', ()=>{
     it('1) --api-key flag wins, is ephemeral, and never touches the store', async()=>{
         const {store} = fake_store({[HOST]: {type: 'api_key', key: 'stored'}});
-        const r = await resolve_credential({api_key: 'flagkey'}, {host: HOST, store, env: {[API_KEY_ENV]: 'envkey'}, now: NOW});
+        const r = await resolve_credential({api_key: 'flagkey'}, {key: HOST, store, env: {[API_KEY_ENV]: 'envkey'}, now: NOW});
         expect(r).toMatchObject({token: 'flagkey', type: 'api_key', source: 'flag', ephemeral: true});
         expect(store.get).not.toHaveBeenCalled();
     });
 
     it('2) <PREFIX>_API_KEY env is used when no flag, ephemeral, store untouched', async()=>{
         const {store} = fake_store({[HOST]: {type: 'api_key', key: 'stored'}});
-        const r = await resolve_credential({}, {host: HOST, store, env: {[API_KEY_ENV]: 'envkey'}, now: NOW});
+        const r = await resolve_credential({}, {key: HOST, store, env: {[API_KEY_ENV]: 'envkey'}, now: NOW});
         expect(r).toMatchObject({token: 'envkey', source: 'env', ephemeral: true});
         expect(store.get).not.toHaveBeenCalled();
     });
 
     it('3) flag beats env', async()=>{
         const {store} = fake_store();
-        const r = await resolve_credential({api_key: 'flagkey'}, {host: HOST, store, env: {[API_KEY_ENV]: 'envkey'}, now: NOW});
+        const r = await resolve_credential({api_key: 'flagkey'}, {key: HOST, store, env: {[API_KEY_ENV]: 'envkey'}, now: NOW});
         expect(r.token).toBe('flagkey');
     });
 
     it('3) falls back to a stored api_key record (not ephemeral)', async()=>{
         const {store} = fake_store({[HOST]: {type: 'api_key', key: 'stored', user: {username: 'u'}}});
-        const r = await resolve_credential({}, {host: HOST, store, env: {}, now: NOW});
+        const r = await resolve_credential({}, {key: HOST, store, env: {}, now: NOW});
         expect(r).toMatchObject({token: 'stored', type: 'api_key', source: 'store', ephemeral: false});
     });
 
     it('returns a stored oauth access token when it is still fresh', async()=>{
         const {store} = fake_store({[HOST]: fresh_oauth()});
         const refresh = vi.fn();
-        const r = await resolve_credential({}, {host: HOST, store, env: {}, now: NOW, refresh});
+        const r = await resolve_credential({}, {key: HOST, store, env: {}, now: NOW, refresh});
         expect(r).toMatchObject({token: 'at', type: 'oauth', source: 'store'});
         expect(refresh).not.toHaveBeenCalled();
     });
@@ -66,30 +66,30 @@ describe('auth/resolve — credential precedence', ()=>{
         const {store} = fake_store({[HOST]: fresh_oauth({expires_at: NOW - 1})});
         const refreshed: Oauth_record = fresh_oauth({access_token: 'new_at', expires_at: NOW + 3_600_000});
         const refresh = vi.fn(async()=>refreshed);
-        const r = await resolve_credential({}, {host: HOST, store, env: {}, now: NOW, refresh});
+        const r = await resolve_credential({}, {key: HOST, store, env: {}, now: NOW, refresh});
         expect(refresh).toHaveBeenCalledOnce();
         expect(store.set).toHaveBeenCalledWith(HOST, refreshed);
         expect(r.token).toBe('new_at');
     });
 
     it('clears the record and errors when an expired token has no refresh token', async()=>{
         const {store} = fake_store({[HOST]: fresh_oauth({expires_at: NOW - 1, refresh_token: undefined})});
-        await expect(resolve_credential({}, {host: HOST, store, env: {}, now: NOW, refresh: vi.fn()}))
+        await expect(resolve_credential({}, {key: HOST, store, env: {}, now: NOW, refresh: vi.fn()}))
             .rejects.toBeInstanceOf(UsageError);
         expect(store.remove).toHaveBeenCalledWith(HOST);
     });
 
     it('clears the record and errors when refresh fails', async()=>{
         const {store} = fake_store({[HOST]: fresh_oauth({expires_at: NOW - 1})});
         const refresh = vi.fn(async()=>{throw new Error('token endpoint said no');});
-        await expect(resolve_credential({}, {host: HOST, store, env: {}, now: NOW, refresh}))
+        await expect(resolve_credential({}, {key: HOST, store, env: {}, now: NOW, refresh}))
             .rejects.toBeInstanceOf(UsageError);
         expect(store.remove).toHaveBeenCalledWith(HOST);
     });
 
     it('errors (UsageError) when nothing is available and writes nothing', async()=>{
         const {store} = fake_store();
-        await expect(resolve_credential({}, {host: HOST, store, env: {}, now: NOW}))
+        await expect(resolve_credential({}, {key: HOST, store, env: {}, now: NOW}))
             .rejects.toBeInstanceOf(UsageError);
         expect(store.set).not.toHaveBeenCalled();
     });
 
@@ -23,7 +23,7 @@ let store: FileCredentialStore;
 
 beforeEach(()=>{
     dir = fs.mkdtempSync(path.join(os.tmpdir(), 'reply-store-'));
-    file = path.join(dir, 'nested', 'hosts.json');
+    file = path.join(dir, 'nested', 'credentials.json');
     store = new FileCredentialStore(file);
 });
 
@@ -34,7 +34,7 @@ afterEach(()=>{
 describe('credentials/FileCredentialStore', ()=>{
     it('returns undefined for a host before anything is stored', async()=>{
         expect(await store.get('oauth.dev.replyapp.io')).toBeUndefined();
-        expect(await store.hosts()).toEqual([]);
+        expect(await store.keys()).toEqual([]);
     });
 
     it('round-trips a record for a host', async()=>{
@@ -47,7 +47,7 @@ describe('credentials/FileCredentialStore', ()=>{
         await store.set('api.reply.io', API_KEY);
         expect(await store.get('oauth.dev.replyapp.io')).toEqual(OAUTH);
         expect(await store.get('api.reply.io')).toEqual(API_KEY);
-        expect((await store.hosts()).sort()).toEqual(['api.reply.io', 'oauth.dev.replyapp.io']);
+        expect((await store.keys()).sort()).toEqual(['api.reply.io', 'oauth.dev.replyapp.io']);
     });
 
     it('overwrites an existing host record', async()=>{
@@ -92,7 +92,7 @@ describe('credentials/FileCredentialStore', ()=>{
     it('treats an empty file as no credentials', async()=>{
         fs.mkdirSync(path.dirname(file), {recursive: true});
         fs.writeFileSync(file, '');
-        expect(await store.hosts()).toEqual([]);
+        expect(await store.keys()).toEqual([]);
     });
 
     it('throws a RuntimeError on a corrupt store file', async()=>{
@@ -105,6 +105,6 @@ describe('credentials/FileCredentialStore', ()=>{
     it('throws a RuntimeError when the file holds a non-object', async()=>{
         fs.mkdirSync(path.dirname(file), {recursive: true});
         fs.writeFileSync(file, '["nope"]');
-        await expect(store.hosts()).rejects.toBeInstanceOf(RuntimeError);
+        await expect(store.keys()).rejects.toBeInstanceOf(RuntimeError);
     });
 });
@@ -2,7 +2,7 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import {resolve_profile, current_profile_name, list_profiles, set_current_profile, PROD} from '../profile';
+import {resolve_profile, current_profile_name, list_profiles, set_current_profile, add_profile, PROD} from '../profile';
 import {UsageError, RuntimeError} from '../utils/errors';
 
 let dir: string;
@@ -62,9 +62,17 @@ describe('profile — no environment abstraction, only a default + user profiles
         expect(p.api_base).toBe('https://b/v3');
     });
 
-    it('throws a UsageError when a profile is missing a URL', ()=>{
-        write_config({profiles: {dev: {authority: 'https://a'}}});
-        expect(()=>resolve_profile('dev', env_for())).toThrow(UsageError);
+    it('inherits missing URLs from the embedded default (prod)', ()=>{
+        write_config({profiles: {'alice@reply.io': {}}});
+        const p = resolve_profile('alice@reply.io', env_for());
+        expect(p).toEqual({name: 'alice@reply.io', authority: PROD.authority, api_base: PROD.api_base});
+    });
+
+    it('inherits per-field: overrides api_base but keeps the prod authority', ()=>{
+        write_config({profiles: {stg: {api_base: 'https://api.stage.reply.io/v3'}}});
+        const p = resolve_profile('stg', env_for());
+        expect(p.authority).toBe(PROD.authority);
+        expect(p.api_base).toBe('https://api.stage.reply.io/v3');
     });
 
     it('throws a RuntimeError on a corrupt config file', ()=>{
@@ -123,3 +131,33 @@ describe('profile — current (persisted) profile', ()=>{
         expect(()=>set_current_profile('nope', env_for())).toThrow(UsageError);
     });
 });
+
+describe('profile — add (create, URLs optional)', ()=>{
+    it('creates a URL-less profile that inherits prod', ()=>{
+        add_profile('alice@reply.io', {}, env_for());
+        expect(resolve_profile('alice@reply.io', env_for())).toEqual({
+            name: 'alice@reply.io', authority: PROD.authority, api_base: PROD.api_base,
+        });
+    });
+
+    it('creates a profile with explicit URLs', ()=>{
+        add_profile('dev', {authority: 'https://oauth.dev.replyapp.io', api_base: 'https://api.dev.reply.io/v3'}, env_for());
+        expect(resolve_profile('dev', env_for())).toMatchObject({
+            authority: 'https://oauth.dev.replyapp.io', api_base: 'https://api.dev.reply.io/v3',
+        });
+    });
+
+    it('preserves other profiles and lets set_current select the new one', ()=>{
+        add_profile('alice@reply.io', {}, env_for());
+        add_profile('bob@reply.io', {}, env_for());
+        set_current_profile('bob@reply.io', env_for());
+        const l = list_profiles(env_for());
+        expect([...l.available].sort()).toEqual(['alice@reply.io', 'bob@reply.io', 'default']);
+        expect(l.current).toBe('bob@reply.io');
+    });
+
+    it('rejects adding the built-in default and empty names', ()=>{
+        expect(()=>add_profile('default', {}, env_for())).toThrow(UsageError);
+        expect(()=>add_profile('   ', {}, env_for())).toThrow(UsageError);
+    });
+});
@@ -26,12 +26,12 @@ describe('utils/errors', ()=>{
 
         it('to_json carries title, code, detail and hint', ()=>{
             const e = new RuntimeError('Credential store is corrupt', {
-                code: 'store.corrupt', detail: '/p/hosts.json', hint: 'delete it and log in again',
+                code: 'store.corrupt', detail: '/p/credentials.json', hint: 'delete it and log in again',
             });
             expect(e.to_json()).toEqual({error: {
                 code: 'store.corrupt',
                 title: 'Credential store is corrupt',
-                detail: '/p/hosts.json',
+                detail: '/p/credentials.json',
                 hint: 'delete it and log in again',
             }});
         });