@chalksurf/cli 0.2.0 → 0.2.1

package/README.md

@@ -2,20 +2,20 @@
 
 Publishable ChalkSurf CLI package.
 
-Current internal release line: `0.1.0`. Expect breaking changes while the CLI is still only used internally.
+Current internal release line: `0.2.1`. Expect breaking changes while the CLI is still only used internally.
 
 ## Installation
 
 Run the published CLI without a global install:
 
 ```bash
-npx @chalksurf/cli@0.1.0 --help
+npx @chalksurf/cli@0.2.1 --help
 ```
 
 Install it globally when you want a persistent local binary:
 
 ```bash
-npm install -g @chalksurf/cli@0.1.0
+npm install -g @chalksurf/cli@0.2.1
 chalksurf --version
 ```
 
@@ -24,7 +24,8 @@ chalksurf --version
 Interactive operator flow:
 
 ```bash
-chalksurf auth login --base-url https://api.chalksurf.com
+chalksurf auth login --profile prod-cztamas --base-url https://chalksurf-api.fly.dev
+chalksurf profile use prod-cztamas
 chalksurf org list
 chalksurf sheet import ./fixtures/algebra.pdf --wait
 ```
@@ -32,10 +33,13 @@ chalksurf sheet import ./fixtures/algebra.pdf --wait
 Headless or agent flow:
 
 ```bash
-CHALKSURF_BASE_URL=https://api.chalksurf.com \
 CHALKSURF_TOKEN=cs_cli_... \
-CHALKSURF_ORGANIZATION_ID=org_123 \
-npx @chalksurf/cli@0.1.0 sheet import --manifest - --wait --json < import.json
+printf '%s' "$CHALKSURF_TOKEN" | npx @chalksurf/cli@0.2.1 auth login \
+  --profile prod-codex \
+  --base-url https://chalksurf-api.fly.dev \
+  --with-token
+
+npx @chalksurf/cli@0.2.1 --profile prod-codex sheet import --manifest - --wait --json < import.json
 ```
 
 Sheet import manifests use top-level `sheets[]`, where each sheet has one `targetFolderPath` and one or more ordered `sources[]`. See [the canonical example](./docs/examples/sheet-import-manifest.json).
@@ -52,18 +56,17 @@ Sheet import manifests use top-level `sheets[]`, where each sheet has one `targe
 
 ## Local And Staging Testing
 
-Use separate config files per environment so local and staging tokens do not overwrite each other:
+Use separate profiles so local, staging, production, human, and agent tokens do not overwrite each other:
 
 ```bash
-export CHALKSURF_CONFIG_PATH=/tmp/chalksurf-local.json
-npm run cli-dev -- auth login --base-url http://localhost:8080
+npm run cli-dev -- auth login --profile dev-cztamas --base-url http://localhost:8080
+npm run cli-dev -- profile use dev-cztamas
 npm run cli-dev -- auth status --json
 npm run cli-dev -- sheet import ./fixtures/algebra.pdf --wait --json
 ```
 
 ```bash
-export CHALKSURF_CONFIG_PATH=/tmp/chalksurf-staging.json
-npm run cli-dev -- auth login --base-url https://staging-api.chalksurf.com
-npm run cli-dev -- auth status --json
-npm run cli-dev -- sheet import https://example.com/worksheet.docx --single-sheet --target-folder Imported --json
+npm run cli-dev -- auth login --profile staging-codex --base-url https://chalksurf-api-staging.fly.dev
+npm run cli-dev -- --profile staging-codex auth status --json
+npm run cli-dev -- --profile staging-codex sheet import https://example.com/worksheet.docx --single-sheet --target-folder Imported --json
 ```

package/dist/bin/chalksurf.js

@@ -7,6 +7,7 @@ import { registerAuthCommands } from '../commands/auth.js';
 import { registerExerciseCommands } from '../commands/exercise.js';
 import { registerJobCommands } from '../commands/job.js';
 import { registerOrgCommands } from '../commands/org.js';
+import { registerProfileCommands } from '../commands/profile.js';
 import { registerSheetCommands } from '../commands/sheet.js';
 import { CliCommandError, createSerializableCliError, serializeCliError } from '../lib/cli-error.js';
 import { createConfigStore } from '../lib/config-store.js';
@@ -42,6 +43,11 @@ const createCli = ({ cwd, configPath, env, now, output, sleep, stdin, promptSecr
         type: 'string',
         global: true,
         describe: 'Organization ID to use for this command',
+    })
+        .option('profile', {
+        type: 'string',
+        global: true,
+        describe: 'CLI profile to use for this command',
     })
         .option('version', {
         type: 'boolean',
@@ -50,6 +56,7 @@ const createCli = ({ cwd, configPath, env, now, output, sleep, stdin, promptSecr
     })
         .command('auth <subcommand>', 'Authentication commands', (authYargs) => registerAuthCommands(authYargs, commandContext), () => { })
         .command('org <subcommand>', 'Organization commands', (orgYargs) => registerOrgCommands(orgYargs, commandContext), () => { })
+        .command('profile <subcommand>', 'Profile commands', (profileYargs) => registerProfileCommands(profileYargs, commandContext), () => { })
         .command('exercise <subcommand>', 'Exercise commands', (exerciseYargs) => registerExerciseCommands(exerciseYargs, commandContext), () => { })
         .command('sheet <subcommand>', 'Exercise sheet commands', (sheetYargs) => registerSheetCommands(sheetYargs, commandContext), () => { })
         .command('job <subcommand>', 'Job commands', (jobYargs) => registerJobCommands(jobYargs, commandContext), () => { })
@@ -74,7 +81,7 @@ const parseCliWithCapturedOutput = async ({ cli, argv, stdout, }) => {
 const hasFlag = (argv, flags) => {
     return argv.some((argument) => flags.includes(argument));
 };
-const topLevelCommands = new Set(['auth', 'org', 'exercise', 'sheet', 'job']);
+const topLevelCommands = new Set(['auth', 'org', 'profile', 'exercise', 'sheet', 'job']);
 const hasTopLevelCommand = (argv) => {
     return argv.some((argument) => topLevelCommands.has(argument));
 };

package/dist/commands/auth.js

@@ -38,10 +38,10 @@ export const registerAuthCommands = (authYargs, context) => {
             default: false,
             describe: 'Read the token from stdin when piping input',
         })
-            .example('chalksurf auth login --base-url https://api.chalksurf.com', 'Prompt for a CLI token and store it locally')
-            .example(`printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login --base-url https://api.chalksurf.com`, 'Read a CLI token from stdin instead of prompting');
+            .example('chalksurf auth login --profile prod-cztamas --base-url https://chalksurf-api.fly.dev', 'Prompt for a CLI token and store it in the prod-cztamas profile')
+            .example(`printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login --profile prod-codex --base-url https://chalksurf-api.fly.dev`, 'Read a CLI token from stdin into an explicit profile');
     }, async (argv) => {
-        const config = await context.configStore.load();
+        const config = await context.configStore.loadProfile({ profileName: argv.profile });
         const resolvedBaseUrl = requireResolvedBaseUrl({
             flagValue: argv.baseUrl,
             env: context.env,
@@ -70,7 +70,7 @@ export const registerAuthCommands = (authYargs, context) => {
             config,
             profile,
         });
-        await context.configStore.update((currentConfig) => ({
+        await context.configStore.update({ profileName: argv.profile }, (currentConfig) => ({
             ...currentConfig,
             token,
             baseUrl: resolvedBaseUrl.value,
@@ -84,6 +84,8 @@ export const registerAuthCommands = (authYargs, context) => {
             baseUrl: resolvedBaseUrl.value,
             baseUrlSource: resolvedBaseUrl.source,
             organization: serializeOrganization(resolvedOrganization.organization),
+            profile: config.profileName,
+            profileSource: config.profileSource,
             user: {
                 email: profile.email,
                 id: profile.id,
@@ -95,14 +97,15 @@ export const registerAuthCommands = (authYargs, context) => {
     })
         .command('status', 'Show the current authentication and organization state', (statusYargs) => statusYargs
         .example('chalksurf auth status', 'Show the current authenticated user and default organization')
-        .example('CHALKSURF_BASE_URL=https://api.chalksurf.com CHALKSURF_TOKEN=cs_cli_... chalksurf auth status --json', 'Inspect the active session in machine-readable mode')
+        .example('chalksurf --profile prod-codex auth status --json', 'Inspect a specific profile in machine-readable mode')
         .epilogue([
         'Resolution order:',
-        '  base URL: --base-url, then CHALKSURF_BASE_URL, then stored config',
-        '  token: CHALKSURF_TOKEN, then stored config',
-        '  organization: --organization, then CHALKSURF_ORGANIZATION_ID, then stored config',
+        '  profile: --profile, then CHALKSURF_PROFILE, then stored default profile',
+        '  base URL: --base-url, then CHALKSURF_BASE_URL, then active profile',
+        '  token: CHALKSURF_TOKEN, then active profile',
+        '  organization: --organization, then CHALKSURF_ORGANIZATION_ID, then active profile',
     ].join('\n')), async (argv) => {
-        const config = await context.configStore.load();
+        const config = await context.configStore.loadProfile({ profileName: argv.profile });
         const resolvedBaseUrl = requireResolvedBaseUrl({
             flagValue: argv.baseUrl,
             env: context.env,
@@ -138,6 +141,8 @@ export const registerAuthCommands = (authYargs, context) => {
             baseUrlSource: resolvedBaseUrl.source,
             organization: serializeOrganization(resolvedOrganization.organization),
             organizationSource: resolvedOrganization.source,
+            profile: config.profileName,
+            profileSource: config.profileSource,
             tokenSource: resolvedToken.source,
             user: {
                 email: profile.email,
@@ -148,16 +153,18 @@ export const registerAuthCommands = (authYargs, context) => {
             command: 'auth status',
         });
     })
-        .command('logout', 'Remove the locally stored CLI token', (logoutYargs) => logoutYargs.example('chalksurf auth logout', 'Remove the stored CLI token from local config'), async () => {
-        const config = await context.configStore.load();
+        .command('logout', 'Remove the locally stored CLI token', (logoutYargs) => logoutYargs.example('chalksurf auth logout', 'Remove the stored CLI token from local config'), async (argv) => {
+        const config = await context.configStore.loadProfile({ profileName: argv.profile });
         const hadStoredToken = Boolean(config.token);
-        await context.configStore.update((currentConfig) => ({
+        await context.configStore.update({ profileName: argv.profile }, (currentConfig) => ({
             ...currentConfig,
             token: undefined,
         }));
         context.output.print({
             clearedStoredToken: hadStoredToken,
             loggedOut: true,
+            profile: config.profileName,
+            profileSource: config.profileSource,
         }, hadStoredToken ? 'Stored CLI token removed.' : 'No stored CLI token was present.', {
             command: 'auth logout',
         });

package/dist/commands/exercise.js

@@ -110,9 +110,9 @@ export const registerExerciseCommands = (exerciseYargs, context) => {
         describe: 'Wait for the queued job to finish',
     })
         .example('chalksurf exercise import ./fixtures/problem-set.pdf --sheet-id 00000000-0000-4000-8000-000000000001 --wait', 'Import a problem set into an existing sheet')
-        .example('cat exercise-import.json | chalksurf exercise import --manifest - --wait --json', 'Drive imports from a manifest in an agent or CI flow')
+        .example('cat exercise-import.json | chalksurf --profile prod-codex exercise import --manifest - --wait --json', 'Drive imports from a manifest in an agent or CI flow')
         .epilogue('When --wait is set, the command exits after the queued import job reaches a terminal state.'), async (argv) => {
-        const config = await context.configStore.load();
+        const config = await context.configStore.loadProfile({ profileName: argv.profile });
         const rawSources = (argv.sources ?? []).map(String);
         const manifestPath = argv.manifest === '' ? '-' : argv.manifest;
         const normalizedRawSources = manifestPath === '-' && rawSources[0] === '-' ? rawSources.slice(1) : rawSources;
@@ -283,9 +283,9 @@ export const registerExerciseCommands = (exerciseYargs, context) => {
         describe: 'Wait for the queued job to finish',
     })
         .example('chalksurf exercise import-solution 00000000-0000-4000-8000-000000000001 ./fixtures/solution.pdf --wait', 'Attach a solution file to an existing exercise')
-        .example('cat exercise-solution-import.json | chalksurf exercise import-solution --manifest - --wait --json', 'Drive solution imports from a manifest in an agent or CI flow')
+        .example('cat exercise-solution-import.json | chalksurf --profile prod-codex exercise import-solution --manifest - --wait --json', 'Drive solution imports from a manifest in an agent or CI flow')
         .epilogue('When --wait is set, the command exits after the queued import job reaches a terminal state.'), async (argv) => {
-        const config = await context.configStore.load();
+        const config = await context.configStore.loadProfile({ profileName: argv.profile });
         const rawSources = (argv.sources ?? []).map(String);
         const manifestPath = argv.manifest === '' ? '-' : argv.manifest;
         const normalizedRawSources = manifestPath === '-' && rawSources[0] === '-' ? rawSources.slice(1) : rawSources;

package/dist/commands/job.js

@@ -18,7 +18,7 @@ export const registerJobCommands = (jobYargs, context) => {
     })
         .example('chalksurf job get job_123', 'Read one job in human-readable mode')
         .example('chalksurf job get job_123 --json', 'Read one job in machine-readable mode'), async (argv) => {
-        const config = await context.configStore.load();
+        const config = await context.configStore.loadProfile({ profileName: argv.profile });
         const resolvedBaseUrl = requireResolvedBaseUrl({
             flagValue: argv.baseUrl,
             env: context.env,
@@ -63,7 +63,7 @@ export const registerJobCommands = (jobYargs, context) => {
     })
         .example('chalksurf job wait job_123 job_124', 'Wait for one or more jobs to reach a terminal state')
         .example('chalksurf job wait job_123 --timeout-ms 60000 --json', 'Poll a job for up to 60 seconds'), async (argv) => {
-        const config = await context.configStore.load();
+        const config = await context.configStore.loadProfile({ profileName: argv.profile });
         const resolvedBaseUrl = requireResolvedBaseUrl({
             flagValue: argv.baseUrl,
             env: context.env,

package/dist/commands/org.js

@@ -14,9 +14,9 @@ const serializeOrganization = ({ organizationId, organizationName, organizationT
 export const registerOrgCommands = (orgYargs, context) => {
     return orgYargs
         .command('list', 'List organizations available to the authenticated user', (listYargs) => listYargs
-        .example('chalksurf org list', 'List organizations for the current session')
-        .example('chalksurf org list --json', 'Inspect the available organizations in machine-readable mode'), async (argv) => {
-        const config = await context.configStore.load();
+        .example('chalksurf org list', 'List organizations for the default profile')
+        .example('chalksurf --profile prod-codex org list --json', 'Inspect organizations for a specific profile'), async (argv) => {
+        const config = await context.configStore.loadProfile({ profileName: argv.profile });
         const resolvedBaseUrl = requireResolvedBaseUrl({
             flagValue: argv.baseUrl,
             env: context.env,
@@ -52,6 +52,8 @@ export const registerOrgCommands = (orgYargs, context) => {
         }));
         context.output.print({
             organizations,
+            profile: config.profileName,
+            profileSource: config.profileSource,
             selectedOrganizationId: resolvedOrganization.organization?.organizationId ?? null,
             selectedOrganizationSource: resolvedOrganization.source,
         }, (result) => result.organizations
@@ -66,9 +68,9 @@ export const registerOrgCommands = (orgYargs, context) => {
             type: 'string',
             describe: 'Organization ID to store as the default',
         })
-            .example('chalksurf org use org_123', 'Store org_123 as the default organization for future commands');
+            .example('chalksurf --profile prod-codex org use org_123', 'Store org_123 in the prod-codex profile');
     }, async (argv) => {
-        const config = await context.configStore.load();
+        const config = await context.configStore.loadProfile({ profileName: argv.profile });
         const resolvedBaseUrl = requireResolvedBaseUrl({
             flagValue: argv.baseUrl,
             env: context.env,
@@ -93,7 +95,7 @@ export const registerOrgCommands = (orgYargs, context) => {
         if (!organization) {
             throw new CliCommandError(`Organization "${String(argv.organizationId)}" is not accessible to the current user.`, 2);
         }
-        await context.configStore.update((currentConfig) => ({
+        await context.configStore.update({ profileName: argv.profile }, (currentConfig) => ({
             ...currentConfig,
             organizationId: organization.organizationId,
         }));
@@ -102,6 +104,8 @@ export const registerOrgCommands = (orgYargs, context) => {
                 ...organization,
                 selected: true,
             }),
+            profile: config.profileName,
+            profileSource: config.profileSource,
         }, (result) => `Default organization set to ${result.organization.name} (${result.organization.id}).`, {
             command: 'org use',
         });

package/dist/commands/profile.js

@@ -0,0 +1,97 @@
+import { CliCommandError } from '../lib/cli-error.js';
+import { assertValidProfileName, resolveProfile } from '../lib/config-store.js';
+const serializeProfile = ({ profileName, profileConfig, selected, }) => {
+    return {
+        baseUrl: profileConfig.baseUrl ?? null,
+        hasToken: Boolean(profileConfig.token),
+        name: profileName,
+        organizationId: profileConfig.organizationId ?? null,
+        selected,
+    };
+};
+const formatProfile = (profile) => {
+    const marker = profile.selected ? '*' : ' ';
+    const baseUrl = profile.baseUrl ?? 'no base URL';
+    const token = profile.hasToken ? 'token' : 'no token';
+    const organization = profile.organizationId ? `org ${profile.organizationId}` : 'no org';
+    return `${marker} ${profile.name} (${baseUrl}, ${token}, ${organization})`;
+};
+export const registerProfileCommands = (profileYargs, context) => {
+    return profileYargs
+        .command('list', 'List locally stored CLI profiles', (listYargs) => listYargs
+        .example('chalksurf profile list', 'List locally stored profiles')
+        .example('chalksurf --profile prod-codex profile list --json', 'Show the active profile in JSON mode'), async (argv) => {
+        const rootConfig = await context.configStore.loadRoot();
+        let activeProfile = null;
+        try {
+            activeProfile =
+                Object.keys(rootConfig.profiles).length === 0
+                    ? null
+                    : resolveProfile({
+                        flagValue: argv.profile,
+                        env: context.env,
+                        config: rootConfig,
+                    });
+        }
+        catch (error) {
+            if (!(error instanceof CliCommandError) || !error.message.startsWith('No active ChalkSurf profile')) {
+                throw error;
+            }
+        }
+        const profiles = Object.entries(rootConfig.profiles).map(([profileName, profileConfig]) => serializeProfile({
+            profileName,
+            profileConfig,
+            selected: profileName === activeProfile?.profileName,
+        }));
+        context.output.print({
+            activeProfile: activeProfile?.profileName ?? null,
+            activeProfileSource: activeProfile?.profileSource ?? null,
+            defaultProfile: rootConfig.defaultProfile ?? null,
+            profiles,
+        }, (result) => result.profiles.length === 0 ? 'No profiles configured.' : result.profiles.map(formatProfile).join('\n'), {
+            command: 'profile list',
+        });
+    })
+        .command('use <profileName>', 'Set the default profile used by the CLI', (useYargs) => useYargs
+        .positional('profileName', {
+        type: 'string',
+        describe: 'Profile name to make the default',
+    })
+        .example('chalksurf profile use prod-cztamas', 'Use prod-cztamas by default for future commands'), async (argv) => {
+        const profileName = String(argv.profileName ?? '');
+        assertValidProfileName(profileName);
+        const rootConfig = await context.configStore.setDefaultProfile(profileName);
+        const profileConfig = rootConfig.profiles[profileName];
+        if (!profileConfig) {
+            throw new CliCommandError(`Profile "${profileName}" does not exist.`, 2);
+        }
+        context.output.print({
+            defaultProfile: profileName,
+            profile: serializeProfile({
+                profileName,
+                profileConfig,
+                selected: true,
+            }),
+        }, (result) => `Default profile set to ${result.defaultProfile}.`, {
+            command: 'profile use',
+        });
+    })
+        .command('delete <profileName>', 'Delete a locally stored CLI profile', (deleteYargs) => deleteYargs
+        .positional('profileName', {
+        type: 'string',
+        describe: 'Profile name to delete',
+    })
+        .example('chalksurf profile delete prod-codex', 'Delete the prod-codex profile'), async (argv) => {
+        const profileName = String(argv.profileName ?? '');
+        assertValidProfileName(profileName);
+        const rootConfig = await context.configStore.deleteProfile(profileName);
+        context.output.print({
+            deletedProfile: profileName,
+            defaultProfile: rootConfig.defaultProfile ?? null,
+        }, (result) => `Deleted profile ${result.deletedProfile}.`, {
+            command: 'profile delete',
+        });
+    })
+        .demandCommand(1)
+        .strict();
+};

package/dist/commands/sheet.js

@@ -271,12 +271,12 @@ export const registerSheetCommands = (sheetYargs, context) => {
     })
         .example('chalksurf sheet import ./fixtures/algebra.pdf --title "OKTV 2014 Round 1" --translate-to english --wait', 'Import a sheet, override its title, and request an English translation')
         .example('chalksurf sheet import ./fixtures/round-1-a.pdf ./fixtures/round-1-b.pdf --single-sheet --target-folder Contests --wait', 'Import multiple source files into one sheet and place the result into a target folder')
-        .example('cat sheet-import.json | chalksurf sheet import --manifest - --wait --json', 'Drive multi-source sheet imports from a manifest in an agent or CI flow')
+        .example('cat sheet-import.json | chalksurf --profile prod-codex sheet import --manifest - --wait --json', 'Drive multi-source sheet imports from a manifest in an agent or CI flow')
         .epilogue([
         'When --wait is set, the command exits only after the full requested import is complete.',
         'For translated sheet imports, that includes generating and storing the requested translations.',
     ].join('\n')), async (argv) => {
-        const config = await context.configStore.load();
+        const config = await context.configStore.loadProfile({ profileName: argv.profile });
         const rawSources = (argv.sources ?? []).map(String);
         const manifestPath = argv.manifest === '' ? '-' : argv.manifest;
         const normalizedRawSources = manifestPath === '-' && rawSources[0] === '-' ? rawSources.slice(1) : rawSources;

package/dist/lib/config-store.js

@@ -5,7 +5,11 @@ import { CliCommandError } from './cli-error.js';
 export const chalksurfBaseUrlEnvVar = 'CHALKSURF_BASE_URL';
 export const chalksurfTokenEnvVar = 'CHALKSURF_TOKEN';
 export const chalksurfOrganizationIdEnvVar = 'CHALKSURF_ORGANIZATION_ID';
+export const chalksurfProfileEnvVar = 'CHALKSURF_PROFILE';
 export const chalksurfConfigPathEnvVar = 'CHALKSURF_CONFIG_PATH';
+export const cliConfigSchemaVersion = 2;
+export const implicitDefaultProfileName = 'default';
+const profileNamePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const normalizeOptionalString = (value) => {
     const trimmedValue = value?.trim();
     return trimmedValue ? trimmedValue : undefined;
@@ -14,13 +18,91 @@ const normalizeStoredBaseUrl = (value) => {
     const normalizedValue = normalizeOptionalString(value);
     return normalizedValue?.replace(/\/+$/, '') || undefined;
 };
-const sanitizeConfig = (config) => {
+const isRecord = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+export const assertValidProfileName = (profileName) => {
+    if (!profileNamePattern.test(profileName)) {
+        throw new CliCommandError(`Invalid profile "${profileName}". Profile names must start with a letter or number and contain only letters, numbers, ".", "_", or "-".`, 2);
+    }
+};
+const normalizeProfileName = (value) => {
+    const profileName = normalizeOptionalString(value);
+    if (!profileName) {
+        return undefined;
+    }
+    assertValidProfileName(profileName);
+    return profileName;
+};
+const sanitizeProfileConfig = (config) => {
     return Object.fromEntries(Object.entries({
         token: normalizeOptionalString(config.token),
         baseUrl: normalizeStoredBaseUrl(config.baseUrl),
         organizationId: normalizeOptionalString(config.organizationId),
     }).filter(([, value]) => value !== undefined));
 };
+const hasProfileConfigValues = (config) => {
+    return Boolean(config.baseUrl || config.token || config.organizationId);
+};
+const readProfileConfig = (value) => {
+    if (!isRecord(value)) {
+        return {};
+    }
+    return sanitizeProfileConfig({
+        baseUrl: typeof value.baseUrl === 'string' ? value.baseUrl : undefined,
+        organizationId: typeof value.organizationId === 'string' ? value.organizationId : undefined,
+        token: typeof value.token === 'string' ? value.token : undefined,
+    });
+};
+const sanitizeRootConfig = (config) => {
+    const profiles = Object.fromEntries(Object.entries(config.profiles)
+        .map(([profileName, profileConfig]) => {
+        const normalizedProfileName = normalizeProfileName(profileName);
+        const sanitizedProfileConfig = sanitizeProfileConfig(profileConfig);
+        return normalizedProfileName && hasProfileConfigValues(sanitizedProfileConfig)
+            ? [normalizedProfileName, sanitizedProfileConfig]
+            : null;
+    })
+        .filter((entry) => entry !== null));
+    const defaultProfile = normalizeProfileName(config.defaultProfile);
+    return {
+        schemaVersion: cliConfigSchemaVersion,
+        ...(defaultProfile && profiles[defaultProfile] ? { defaultProfile } : {}),
+        profiles,
+    };
+};
+const readRootConfig = (value) => {
+    if (!isRecord(value)) {
+        return { schemaVersion: cliConfigSchemaVersion, profiles: {} };
+    }
+    if (isRecord(value.profiles)) {
+        const profiles = Object.fromEntries(Object.entries(value.profiles)
+            .map(([profileName, profileConfig]) => {
+            const sanitizedProfileConfig = readProfileConfig(profileConfig);
+            return hasProfileConfigValues(sanitizedProfileConfig)
+                ? [profileName, sanitizedProfileConfig]
+                : null;
+        })
+            .filter((entry) => entry !== null));
+        return sanitizeRootConfig({
+            schemaVersion: cliConfigSchemaVersion,
+            defaultProfile: typeof value.defaultProfile === 'string' ? value.defaultProfile : undefined,
+            profiles,
+        });
+    }
+    const legacyProfile = readProfileConfig(value);
+    if (!hasProfileConfigValues(legacyProfile)) {
+        return { schemaVersion: cliConfigSchemaVersion, profiles: {} };
+    }
+    return {
+        schemaVersion: cliConfigSchemaVersion,
+        defaultProfile: implicitDefaultProfileName,
+        profiles: {
+            [implicitDefaultProfileName]: legacyProfile,
+        },
+    };
+};
+const rootConfigHasProfiles = (config) => Object.keys(config.profiles).length > 0;
 const getDefaultConfigPath = ({ env, platform, homeDirectory, }) => {
     const explicitConfigPath = normalizeOptionalString(env[chalksurfConfigPathEnvVar]);
     if (explicitConfigPath) {
@@ -73,6 +155,24 @@ export const resolveToken = ({ env, config }) => {
     }
     return { source: 'none' };
 };
+export const resolveProfile = ({ flagValue, env, config, }) => {
+    const flagProfileName = normalizeProfileName(flagValue);
+    if (flagProfileName) {
+        return { profileName: flagProfileName, profileSource: 'flag' };
+    }
+    const envProfileName = normalizeProfileName(env[chalksurfProfileEnvVar]);
+    if (envProfileName) {
+        return { profileName: envProfileName, profileSource: 'env' };
+    }
+    const defaultProfile = normalizeProfileName(config.defaultProfile);
+    if (defaultProfile) {
+        return { profileName: defaultProfile, profileSource: 'config' };
+    }
+    if (!rootConfigHasProfiles(config)) {
+        return { profileName: implicitDefaultProfileName, profileSource: 'implicit-default' };
+    }
+    throw new CliCommandError(`No active ChalkSurf profile selected. Pass --profile, set ${chalksurfProfileEnvVar}, or run "chalksurf profile use <profile>".`, 2);
+};
 export const resolveOrganization = ({ flagValue, env, config, profile, }) => {
     const flagOrganizationId = normalizeOptionalString(flagValue);
     if (flagOrganizationId) {
@@ -134,14 +234,23 @@ export const resolveOrganization = ({ flagValue, env, config, profile, }) => {
 export const createConfigStore = ({ configPath, env = process.env, platform = process.platform, homeDirectory = homedir(), fs = { chmod, mkdir, readFile, rm, writeFile }, } = {}) => {
     const resolvedConfigPath = configPath || getDefaultConfigPath({ env, platform, homeDirectory });
     const load = async () => {
+        const rootConfig = await loadRoot();
+        const resolvedProfile = resolveProfile({ env, config: rootConfig });
+        const profileConfig = rootConfig.profiles[resolvedProfile.profileName] ?? {};
+        return {
+            ...profileConfig,
+            ...resolvedProfile,
+        };
+    };
+    const loadRoot = async () => {
         try {
             const configContents = await fs.readFile(resolvedConfigPath, 'utf8');
             const parsedConfig = JSON.parse(configContents);
-            return sanitizeConfig(parsedConfig);
+            return readRootConfig(parsedConfig);
         }
         catch (error) {
             if (error.code === 'ENOENT') {
-                return {};
+                return { schemaVersion: cliConfigSchemaVersion, profiles: {} };
             }
             if (error instanceof SyntaxError) {
                 throw new CliCommandError(`Failed to parse CLI config at ${resolvedConfigPath}.`, 2);
@@ -149,9 +258,18 @@ export const createConfigStore = ({ configPath, env = process.env, platform = pr
             throw error;
         }
     };
-    const save = async (config) => {
-        const sanitizedConfig = sanitizeConfig(config);
-        if (Object.keys(sanitizedConfig).length === 0) {
+    const loadProfile = async ({ profileName } = {}) => {
+        const rootConfig = await loadRoot();
+        const resolvedProfile = resolveProfile({ flagValue: profileName, env, config: rootConfig });
+        const profileConfig = rootConfig.profiles[resolvedProfile.profileName] ?? {};
+        return {
+            ...profileConfig,
+            ...resolvedProfile,
+        };
+    };
+    const saveRoot = async (config) => {
+        const sanitizedConfig = sanitizeRootConfig(config);
+        if (!rootConfigHasProfiles(sanitizedConfig)) {
             await fs.rm(resolvedConfigPath, { force: true });
             return sanitizedConfig;
         }
@@ -162,15 +280,75 @@ export const createConfigStore = ({ configPath, env = process.env, platform = pr
         await fs.chmod(resolvedConfigPath, 0o600);
         return sanitizedConfig;
     };
-    const update = async (updater) => {
-        const currentConfig = await load();
-        const nextConfig = await updater(currentConfig);
-        return await save(nextConfig);
+    const save = async (config) => {
+        const rootConfig = await loadRoot();
+        const nextProfileConfig = sanitizeProfileConfig(config);
+        const nextRootConfig = {
+            ...rootConfig,
+            profiles: {
+                ...rootConfig.profiles,
+            },
+        };
+        if (hasProfileConfigValues(nextProfileConfig)) {
+            nextRootConfig.profiles[config.profileName] = nextProfileConfig;
+        }
+        else {
+            delete nextRootConfig.profiles[config.profileName];
+        }
+        if (config.profileSource === 'implicit-default' && hasProfileConfigValues(nextProfileConfig)) {
+            nextRootConfig.defaultProfile = config.profileName;
+        }
+        return await saveRoot(nextRootConfig);
+    };
+    const update = async ({ profileName }, updater) => {
+        const currentConfig = await loadProfile({ profileName });
+        const nextProfileConfig = await updater(currentConfig);
+        return await save({
+            ...nextProfileConfig,
+            profileName: currentConfig.profileName,
+            profileSource: currentConfig.profileSource,
+        });
+    };
+    const setDefaultProfile = async (profileName) => {
+        const normalizedProfileName = normalizeProfileName(profileName);
+        if (!normalizedProfileName) {
+            throw new CliCommandError('Profile name is required.', 2);
+        }
+        const rootConfig = await loadRoot();
+        if (!rootConfig.profiles[normalizedProfileName]) {
+            throw new CliCommandError(`Profile "${normalizedProfileName}" does not exist. Run "chalksurf auth login --profile ${normalizedProfileName} --base-url <url>" first.`, 2);
+        }
+        return await saveRoot({
+            ...rootConfig,
+            defaultProfile: normalizedProfileName,
+        });
+    };
+    const deleteProfile = async (profileName) => {
+        const normalizedProfileName = normalizeProfileName(profileName);
+        if (!normalizedProfileName) {
+            throw new CliCommandError('Profile name is required.', 2);
+        }
+        const rootConfig = await loadRoot();
+        if (!rootConfig.profiles[normalizedProfileName]) {
+            throw new CliCommandError(`Profile "${normalizedProfileName}" does not exist.`, 2);
+        }
+        const profiles = { ...rootConfig.profiles };
+        delete profiles[normalizedProfileName];
+        return await saveRoot({
+            schemaVersion: cliConfigSchemaVersion,
+            ...(rootConfig.defaultProfile === normalizedProfileName ? {} : { defaultProfile: rootConfig.defaultProfile }),
+            profiles,
+        });
     };
     return {
         path: resolvedConfigPath,
         load,
+        loadProfile,
+        loadRoot,
         save,
+        saveRoot,
         update,
+        setDefaultProfile,
+        deleteProfile,
     };
 };

package/docs/agents.md

@@ -4,21 +4,29 @@ Use this flow when ChalkSurf is driven by Codex, CI, or another orchestration la
 
 ## Authentication Strategy
 
-Prefer environment variables over interactive config:
+Agents must always use an explicit profile. The profile name must follow the
+`ENV-AGENT_TYPE` convention, such as `prod-codex`, `staging-codex`, `dev-claude`,
+or `prod-claude`.
 
 ```bash
-export CHALKSURF_BASE_URL=https://api.chalksurf.com
-export CHALKSURF_TOKEN=cs_cli_...
-export CHALKSURF_ORGANIZATION_ID=org_123
+chalksurf --profile prod-codex auth status --json
 ```
 
-Check the session in machine-readable mode:
+Do not rely on the default profile in agent-driven runs. The default profile is
+for the human operator's terminal workflow and may point at a different
+environment, user token, or selected organization.
+
+Create or refresh an agent profile explicitly:
 
 ```bash
-chalksurf auth status --json
+printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login \
+  --profile prod-codex \
+  --base-url https://chalksurf-api.fly.dev \
+  --with-token
 ```
 
-Avoid `auth login` for short-lived runs unless you explicitly want local persistence.
+Use `CHALKSURF_TOKEN` only as the source for login or as a short-lived override.
+Prefer storing the token in the explicit agent profile for repeated Codex/CI runs.
 
 ## Command Contract
 
@@ -31,7 +39,7 @@ For agent-driven imports, always use:
 Recommended invocation shape:
 
 ```bash
-chalksurf sheet import --manifest - --wait --json
+chalksurf --profile prod-codex sheet import --manifest - --wait --json
 ```
 
 In `--json` mode:
@@ -131,7 +139,7 @@ Each job includes:
 For example:
 
 ```bash
-cat import.json | chalksurf sheet import --manifest - --wait --json
+cat import.json | chalksurf --profile prod-codex sheet import --manifest - --wait --json
 ```
 
 On success, the envelope looks like:
@@ -168,13 +176,13 @@ Recommended workflow:
 3. Codex builds a sheet-import manifest with one `sheets[]` entry per resulting sheet.
 4. Codex groups multiple source files inside one `sources[]` array when they belong to the same resulting sheet.
 5. Codex sets `translateTo: ["english"]` on the sheet entries that should produce an English translation.
-6. Codex runs `chalksurf sheet import --manifest - --wait --json`.
+6. Codex runs `chalksurf --profile prod-codex sheet import --manifest - --wait --json`.
 7. Codex inspects `result.summary.failed`, `result.summary.timedOut`, and `jobs` to decide whether to retry or report failures.
 
 Minimal shell shape:
 
 ```bash
-cat import.json | chalksurf sheet import --manifest - --wait --json
+cat import.json | chalksurf --profile prod-codex sheet import --manifest - --wait --json
 ```
 
 The discovery step belongs outside the ChalkSurf CLI. The CLI contract starts at a concrete manifest and ends at structured import results.

package/docs/manual.md

@@ -4,16 +4,25 @@ Use this flow when a person is driving the CLI directly from a terminal.
 
 ## Authentication
 
-Interactive login stores the token and base URL in the local CLI config:
+Interactive login stores the token and base URL in a named profile:
 
 ```bash
-chalksurf auth login --base-url https://api.chalksurf.com
+chalksurf auth login --profile prod-cztamas --base-url https://chalksurf-api.fly.dev
 ```
 
 The same command also works with piped stdin:
 
 ```bash
-printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login --base-url https://api.chalksurf.com
+printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login \
+  --profile prod-cztamas \
+  --base-url https://chalksurf-api.fly.dev \
+  --with-token
+```
+
+Set the profile you want to use by default in your terminal workflow:
+
+```bash
+chalksurf profile use prod-cztamas
 ```
 
 Check what the CLI will use for the current session:
@@ -24,9 +33,10 @@ chalksurf auth status
 
 Config resolution rules:
 
-- `--base-url` overrides `CHALKSURF_BASE_URL`, which overrides the stored config.
-- `CHALKSURF_TOKEN` overrides the stored config token.
-- `--organization` overrides manifest `organizationId`, which overrides `CHALKSURF_ORGANIZATION_ID`, which overrides the stored config.
+- `--profile` overrides `CHALKSURF_PROFILE`, which overrides the stored default profile.
+- `--base-url` overrides `CHALKSURF_BASE_URL`, which overrides the active profile.
+- `CHALKSURF_TOKEN` overrides the active profile token.
+- `--organization` overrides manifest `organizationId`, which overrides `CHALKSURF_ORGANIZATION_ID`, which overrides the active profile.
 
 ## Organization Selection
 
@@ -42,6 +52,12 @@ Store a default organization for future commands:
 chalksurf org use org_123
 ```
 
+Store a default organization in a different profile without changing your default profile:
+
+```bash
+chalksurf --profile prod-codex org use org_456
+```
+
 Override it for one command:
 
 ```bash
@@ -132,11 +148,12 @@ Missing auth:
 chalksurf auth status
 ```
 
-Use a separate config file when switching between local, staging, and production:
+Use profiles when switching between local, staging, production, humans, and agents:
 
 ```bash
-export CHALKSURF_CONFIG_PATH=/tmp/chalksurf-staging.json
-chalksurf auth login --base-url https://staging-api.chalksurf.com
+chalksurf auth login --profile staging-cztamas --base-url https://chalksurf-api-staging.fly.dev
+chalksurf auth login --profile prod-cztamas --base-url https://chalksurf-api.fly.dev
+chalksurf profile use prod-cztamas
 ```
 
 Use JSON mode when you need exact machine-readable output:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalksurf/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "engines": {