@quonfig/cli 0.0.18 → 0.0.20

package/dist/commands/log-level.d.ts

@@ -0,0 +1,27 @@
+import { APICommand } from '../index.js';
+import { JsonObj } from '../result.js';
+/**
+ * Convenience command for log-level configs.
+ *
+ *   qfg log-level log-level.my-app --value=WARN
+ *     → creates the config (delegates to `qfg create --type log_level`)
+ *
+ *   qfg log-level log-level.my-app --target=MyPackage.Service --value=INFO
+ *     → adds a targeting rule on "${SDK_LOGGER_CONTEXT}" to an existing
+ *       config, using PROP_STARTS_WITH_ONE_OF. Lets agents dial a single
+ *       logger up/down without pull+edit+push.
+ */
+export default class LogLevel extends APICommand {
+    static args: {
+        name: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        environment: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        target: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        value: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+    };
+    run(): Promise<JsonObj | void>;
+    private addTargetingRule;
+}

package/dist/commands/log-level.js

@@ -0,0 +1,197 @@
+import { Args, Flags } from '@oclif/core';
+import { APICommand } from '../index.js';
+import { checkmark } from '../util/color.js';
+import { LOG_LEVELS, LOG_LEVEL_KEY_PREFIX, isLogLevel } from '../util/log-levels.js';
+const SDK_LOGGER_CONTEXT = 'quonfig-sdk-logging.key';
+/**
+ * Convenience command for log-level configs.
+ *
+ *   qfg log-level log-level.my-app --value=WARN
+ *     → creates the config (delegates to `qfg create --type log_level`)
+ *
+ *   qfg log-level log-level.my-app --target=MyPackage.Service --value=INFO
+ *     → adds a targeting rule on "${SDK_LOGGER_CONTEXT}" to an existing
+ *       config, using PROP_STARTS_WITH_ONE_OF. Lets agents dial a single
+ *       logger up/down without pull+edit+push.
+ */
+export default class LogLevel extends APICommand {
+    static args = {
+        name: Args.string({
+            description: `log-level key (must start with "${LOG_LEVEL_KEY_PREFIX}", e.g. ${LOG_LEVEL_KEY_PREFIX}my-app)`,
+            required: true,
+        }),
+    };
+    static description = `Create or add targeting rules to a log-level config.
+
+Log-level keys must start with "${LOG_LEVEL_KEY_PREFIX}" (e.g. ${LOG_LEVEL_KEY_PREFIX}my-app). The
+default value applies to every logger in that service unless a targeting
+rule matches first.
+
+Two modes:
+
+  1. Create a new log-level config with a default value:
+       qfg log-level ${LOG_LEVEL_KEY_PREFIX}my-app --value=WARN
+
+  2. Add a per-logger targeting rule to an existing config. SDKs populate
+     the "${SDK_LOGGER_CONTEXT}" context automatically from the logger path,
+     so this rule fires for any logger whose name starts with --target:
+       qfg log-level ${LOG_LEVEL_KEY_PREFIX}my-app --target=MyPackage.Noisy --value=ERROR
+
+     Pass --target multiple times to match any of several prefixes (OR).
+     Pass --environment=<env> to scope the rule to a single environment.
+
+To update the catch-all default for an existing log level, use set-default:
+  qfg set-default ${LOG_LEVEL_KEY_PREFIX}my-app --value=DEBUG --environment=production
+
+For more complex rules (regex, multi-criterion, exact match) edit the JSON:
+  qfg pull && $EDITOR log-levels/${LOG_LEVEL_KEY_PREFIX}my-app.json
+  qfg config-schema            # full operator reference`;
+    static examples = [
+        `<%= config.bin %> <%= command.id %> ${LOG_LEVEL_KEY_PREFIX}my-app --value=WARN`,
+        `<%= config.bin %> <%= command.id %> ${LOG_LEVEL_KEY_PREFIX}my-app --target=MyPackage.Noisy --value=ERROR`,
+        `<%= config.bin %> <%= command.id %> ${LOG_LEVEL_KEY_PREFIX}my-app --target=A --target=B --value=DEBUG`,
+        `<%= config.bin %> <%= command.id %> ${LOG_LEVEL_KEY_PREFIX}my-app --target=Chatty --value=INFO --environment=production`,
+    ];
+    static flags = {
+        environment: Flags.string({
+            description: 'when used with --target, scope the rule to this environment instead of the default',
+        }),
+        target: Flags.string({
+            description: `logger path prefix (matched via PROP_STARTS_WITH_ONE_OF on "${SDK_LOGGER_CONTEXT}"); repeatable`,
+            multiple: true,
+        }),
+        value: Flags.string({
+            description: 'log level — either the new default (create mode) or the level for the targeted loggers',
+            options: [...LOG_LEVELS],
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(LogLevel);
+        if (!args.name.startsWith(LOG_LEVEL_KEY_PREFIX)) {
+            return this.err(`Log level key "${args.name}" must start with "${LOG_LEVEL_KEY_PREFIX}". Try: ${LOG_LEVEL_KEY_PREFIX}${args.name}`);
+        }
+        if (!flags.target || flags.target.length === 0) {
+            // No targeting — delegate to create.
+            if (flags.environment) {
+                return this.err('--environment requires --target. To change the default for an existing log level in an environment, use: qfg set-default');
+            }
+            const argv = [args.name, '--type=log_level'];
+            if (flags.value)
+                argv.push(`--value=${flags.value}`);
+            if (this.jsonEnabled())
+                argv.push('--json');
+            return this.config.runCommand('create', argv);
+        }
+        // Targeting mode — add a rule on quonfig-sdk-logging.key.
+        if (!flags.value) {
+            return this.err('--value is required with --target (the level the targeted loggers should use)');
+        }
+        return this.addTargetingRule(args.name, flags.target, flags.value, flags.environment);
+    }
+    async addTargetingRule(key, targets, levelRaw, environment) {
+        const level = levelRaw.toUpperCase();
+        if (!isLogLevel(level)) {
+            return this.err(`Invalid log level "${levelRaw}". Must be one of: ${LOG_LEVELS.join(', ')}`);
+        }
+        // Fetch current config — we need the commitSha for optimistic concurrency
+        // plus the existing rules so we can merge rather than replace.
+        const detailRequest = await this.apiClient.post('/api/v1/metadata/getByKey', {
+            workspaceId: this.workspaceId,
+            key,
+        });
+        if (!detailRequest.ok) {
+            if (detailRequest.status === 404) {
+                return this.err(`Log level "${key}" does not exist. Create it first:\n  qfg log-level ${key} --value=INFO`);
+            }
+            return this.err(`Failed to fetch log level: ${detailRequest.status}`, { serverError: detailRequest.error });
+        }
+        const current = detailRequest.json;
+        const newRule = {
+            criteria: [
+                {
+                    operator: 'PROP_STARTS_WITH_ONE_OF',
+                    propertyName: SDK_LOGGER_CONTEXT,
+                    // Schema: CriterionSchema.valueToMatch is a Value, i.e. { type, value }.
+                    // For string-list operators like PROP_STARTS_WITH_ONE_OF this is a string_list.
+                    valueToMatch: { type: 'string_list', value: [...targets] },
+                },
+            ],
+            value: { type: 'log_level', value: level },
+        };
+        // Merge semantics: if an existing rule has the same exact targeting
+        // criterion (same propertyName, same valueToMatch set), replace its value.
+        // Otherwise insert the new rule before the catch-all so it takes priority.
+        const existingRules = environment
+            ? findEnvRules(current, environment)
+            : current.default?.rules ?? [];
+        const mergedRules = mergeTargetingRule(existingRules, newRule);
+        const logLevelPatch = environment
+            ? { environments: replaceEnvRules(current.environments ?? [], environment, mergedRules) }
+            : { default: { rules: mergedRules } };
+        const updateRequest = await this.apiClient.post('/api/v1/logLevels/update', {
+            workspaceId: this.workspaceId,
+            logLevelKey: key,
+            logLevel: logLevelPatch,
+            expectedCommitSha: current.commitSha,
+        });
+        if (!updateRequest.ok) {
+            return this.err(`Failed to update log level: ${updateRequest.status}`, { serverError: updateRequest.error });
+        }
+        const scope = environment ? `environment=${environment}` : 'default';
+        const targetList = targets.join(', ');
+        return this.ok(`${checkmark} Set log level ${level} for loggers starting with [${targetList}] on ${key} (${scope})`, {
+            key,
+            targets,
+            value: level,
+            environment: environment ?? null,
+        });
+    }
+}
+function findEnvRules(config, environment) {
+    const env = (config.environments ?? []).find((e) => e.id === environment);
+    return env?.rules ?? [];
+}
+function replaceEnvRules(envs, environment, rules) {
+    const hasEnv = envs.some((e) => e.id === environment);
+    return hasEnv ? envs.map((e) => (e.id === environment ? { ...e, rules } : e)) : [...envs, { id: environment, rules }];
+}
+function mergeTargetingRule(existing, incoming) {
+    const incomingTargets = new Set(stringListTargets(incoming.criteria[0].valueToMatch));
+    const incomingPropertyName = incoming.criteria[0].propertyName;
+    let replaced = false;
+    const next = existing.map((rule) => {
+        if (rule.criteria.length !== 1)
+            return rule;
+        const c = rule.criteria[0];
+        if (c.operator !== 'PROP_STARTS_WITH_ONE_OF')
+            return rule;
+        if (c.propertyName !== incomingPropertyName)
+            return rule;
+        const existingTargets = new Set(stringListTargets(c.valueToMatch));
+        if (existingTargets.size !== incomingTargets.size)
+            return rule;
+        for (const t of existingTargets)
+            if (!incomingTargets.has(t))
+                return rule;
+        replaced = true;
+        return { ...rule, value: incoming.value };
+    });
+    if (replaced)
+        return next;
+    // Prepend — it must win against any catch-all rule that's already there.
+    return [incoming, ...existing];
+}
+/**
+ * Pull the string array out of a `valueToMatch` value. Handles the wrapped
+ * `{type: 'string_list', value: [...]}` envelope that the schema requires,
+ * plus a defensive fallback for the bare-array shape (older data or tests).
+ */
+function stringListTargets(v) {
+    if (Array.isArray(v))
+        return v;
+    if (v && typeof v === 'object' && Array.isArray(v.value)) {
+        return v.value;
+    }
+    return [];
+}

package/dist/commands/pull.js

@@ -2,10 +2,10 @@ import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../index.js';
-import { getActiveProfile, loadAuthConfig } from '../util/token-storage.js';
 import { loadGiteaToken, isGiteaTokenExpired, saveGiteaToken } from '../util/gitea-token-storage.js';
 import { mintAndStoreGiteaReadToken, mintGiteaToken } from '../util/gitea-api.js';
 import { readWorkspaceSlug, writeWorkspaceSlug } from '../util/quonfig-json.js';
+import { resolveWorkspaceUuid } from '../util/resolve-workspace.js';
 import { isGitRepo, getRemoteUrl, gitFetch, gitSetRemote, canFastForward, hasDivergedFromRemote, gitMergeFfOnly, gitClone, displayUrl, } from '../util/git-ops.js';
 export default class Pull extends BaseCommand {
     static description = `Clone or update a local copy of your workspace config files.
@@ -41,20 +41,10 @@ CLI shortcuts (no JSON editing needed for simple cases):
             return this.err('No directory specified. Use --dir <path> or set QUONFIG_DIR.');
         }
         const resolvedDir = path.resolve(dir);
-        // Resolve workspace ID
-        let workspaceId = flags.workspace;
-        if (!workspaceId) {
-            const authConfig = await loadAuthConfig();
-            if (!authConfig) {
-                return this.err('Not logged in. Please run `qfg login` first.');
-            }
-            const activeProfile = getActiveProfile();
-            const profile = authConfig.profiles[activeProfile] || authConfig.profiles[authConfig.defaultProfile || 'default'];
-            if (!profile) {
-                return this.err('No active profile found. Please run `qfg login` first.');
-            }
-            workspaceId = profile.workspace;
-        }
+        // Resolve workspace ID — supports both OAuth and QUONFIG_API_KEY paths,
+        // mirroring what APICommand does via get-client.ts so `qfg pull` behaves
+        // the same in CI as `qfg create` or `qfg push`.
+        const workspaceId = await resolveWorkspaceUuid(this, flags.workspace);
         this.verboseLog('Pull', { workspaceId, dir: resolvedDir });
         // Get or mint Gitea read token
         const tokenEntry = await this.resolveTokenEntry(workspaceId);

package/dist/commands/push.js

@@ -8,7 +8,7 @@ import { mintGiteaToken } from '../util/gitea-api.js';
 import { getRemoteUrl, gitFetch, gitSetRemote, isGitRepo, } from '../util/git-ops.js';
 import { PushFatalError, runPush } from '../push/run-push.js';
 import { computeBarePathDiff } from '../push/bare-path-diff.js';
-import { getActiveProfile, loadAuthConfig } from '../util/token-storage.js';
+import { resolveWorkspaceUuid } from '../util/resolve-workspace.js';
 const execFile = util.promisify(execFileCb);
 export default class Push extends BaseCommand {
     static description = `Push local config changes up to your workspace on Quonfig cloud.
@@ -60,20 +60,10 @@ Enforces three guards before touching the remote:
             return this.err('No directory specified. Use --dir <path> or set QUONFIG_DIR.');
         }
         const resolvedDir = path.resolve(dir);
-        // Resolve requested target: --workspace overrides the active profile.
-        let requestedTarget = flags.workspace;
-        if (!requestedTarget) {
-            const authConfig = await loadAuthConfig();
-            if (!authConfig) {
-                return this.err('No active profile workspace; pass --workspace or run `qfg login`.');
-            }
-            const activeProfile = getActiveProfile();
-            const profile = authConfig.profiles[activeProfile] || authConfig.profiles[authConfig.defaultProfile || 'default'];
-            if (!profile || !profile.workspace) {
-                return this.err('No active profile workspace; pass --workspace or run `qfg login`.');
-            }
-            requestedTarget = profile.workspace;
-        }
+        // Resolve requested target. --workspace > QUONFIG_WORKSPACE > active OAuth
+        // profile. Supports API-key mode for headless runs so `qfg push` behaves
+        // the same way `qfg create` does (both resolve via resolve-workspace.ts).
+        const requestedTarget = await resolveWorkspaceUuid(this, flags.workspace);
         const { deps, cleanup } = buildRealDeps(this);
         try {
             const result = await runPush({

package/dist/commands/set-default.js

@@ -192,7 +192,7 @@ To see all current values and rules for a flag:
             successMessage = `Successfully changed default to \`${value}\``;
             if (secret.selected) {
                 // Handle encrypted values using shared utility
-                const encryptedValueResult = await makeConfidentialValue(this, value, secret, environment.id);
+                const encryptedValueResult = await makeConfidentialValue(this, value, secret, environment.name);
                 if (!encryptedValueResult.ok) {
                     return this.err(encryptedValueResult.message || 'Failed to encrypt value');
                 }

package/dist/commands/workspace/create.d.ts

@@ -0,0 +1,20 @@
+import type { JsonObj } from '../../result.js';
+import { BaseCommand } from '../../index.js';
+export default class WorkspaceCreate extends BaseCommand {
+    static args: {
+        slug: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        name: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        org: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+    };
+    run(): Promise<JsonObj | void>;
+    /**
+     * oRPC surfaces structured errors as {json: {code, message, ...}} or
+     * {error: {...}}. Extract the message for display; fall back to raw
+     * text when the body isn't JSON.
+     */
+    private extractErrorMessage;
+}

package/dist/commands/workspace/create.js

@@ -0,0 +1,156 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../index.js';
+import { getApiUrl } from '../../util/domain-urls.js';
+import { getValidAccessToken } from '../../util/get-valid-token.js';
+/**
+ * Slugify matches the UI's rules exactly (see
+ * app-quonfig/src/app/(app)/workspaces/new/page.tsx): lowercase, any
+ * non-alphanumeric run → single hyphen, strip leading/trailing hyphens.
+ * The server re-runs this for safety, but we run it here so the user
+ * sees the canonical slug in confirmation output.
+ */
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replaceAll(/[^\da-z]+/g, '-')
+        .replaceAll(/^-|-$/g, '');
+}
+export default class WorkspaceCreate extends BaseCommand {
+    static args = {
+        slug: Args.string({
+            description: 'Workspace slug (lowercase letters, numbers, hyphens)',
+            required: true,
+        }),
+    };
+    static description = "Create a new workspace. Provisions the Gitea repo and default environments, identical to the app's New Workspace UI.";
+    static examples = [
+        '<%= config.bin %> <%= command.id %> my-team',
+        '<%= config.bin %> <%= command.id %> lt-21-smoke --name "Load Test 21"',
+        '<%= config.bin %> <%= command.id %> my-team --org 11111111-1111-1111-1111-111111111111',
+    ];
+    static flags = {
+        name: Flags.string({
+            description: 'Human-readable display name (defaults to the slug)',
+            required: false,
+        }),
+        org: Flags.string({
+            description: 'Organization UUID or slug. Required when you belong to more than one organization; inferred otherwise.',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(WorkspaceCreate);
+        const slug = slugify(args.slug);
+        if (!slug) {
+            return this.err(`"${args.slug}" does not produce a valid slug. Use letters, numbers, or hyphens.`);
+        }
+        // Resolve auth via the same path every other command uses. We
+        // don't require an active-workspace profile (AuthConfig) — the
+        // whole point of this command is to create one — but we do need a
+        // valid bearer token / API key.
+        let accessToken;
+        try {
+            accessToken = await getValidAccessToken();
+        }
+        catch {
+            return this.err('Not logged in. Run `qfg login` first.');
+        }
+        const apiUrl = getApiUrl();
+        const body = { slug };
+        if (flags.name)
+            body.name = flags.name;
+        if (flags.org) {
+            // Accept either a UUID (from the API) or a human-readable slug.
+            // The server resolves the slug to the local org UUID.
+            const uuidPattern = /^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i;
+            if (uuidPattern.test(flags.org)) {
+                body.organizationId = flags.org;
+            }
+            else {
+                body.organizationSlug = flags.org;
+            }
+        }
+        this.verboseLog('WorkspaceCreate', { apiUrl, body });
+        let res;
+        try {
+            res = await fetch(`${apiUrl}/api/v1/workspaces/create`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ json: body }),
+            });
+        }
+        catch (error) {
+            return this.err(`Request failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (res.status === 401 || res.status === 403) {
+            return this.err(`Authentication/authorization failed (HTTP ${res.status}). Run \`qfg login\` to re-authenticate.`);
+        }
+        if (res.status === 409) {
+            const detail = await this.extractErrorMessage(res);
+            // Prefer the server's message when present (already clear); fall
+            // back to a generated hint otherwise.
+            return this.err(detail || `Workspace "${slug}" already exists. Pick a different slug (e.g. ${slug}-2).`);
+        }
+        if (res.status === 400) {
+            const detail = await this.extractErrorMessage(res);
+            if (detail.includes('more than one organization')) {
+                return this.err(`${detail} Re-run with --org <uuid>. You can list available orgs from the app UI.`);
+            }
+            return this.err(`Bad request (HTTP 400): ${detail}`);
+        }
+        if (!res.ok) {
+            const detail = await this.extractErrorMessage(res);
+            return this.err(`Workspace creation failed (HTTP ${res.status}): ${detail}`);
+        }
+        const payload = (await res.json());
+        const created = (payload.json ?? payload);
+        if (!created?.workspaceId) {
+            return this.err('Unexpected response from server — no workspaceId returned.');
+        }
+        this.log('');
+        this.log(`Workspace created.`);
+        this.log(`  ID:          ${created.workspaceId}`);
+        this.log(`  Slug:        ${created.workspaceSlug}`);
+        if (created.organizationSlug) {
+            this.log(`  Org:         ${created.organizationSlug}`);
+        }
+        this.log(`  Git repo:    ${created.gitRepoUrl}`);
+        if (created.gitRepoFullName) {
+            this.log(`  Gitea:       ${created.gitRepoFullName}`);
+        }
+        this.log(`  Envs:        ${created.environments.map((e) => e.name).join(', ')}`);
+        this.log('');
+        this.log(`To use this workspace locally:`);
+        this.log(`  qfg workspace switch ${created.workspaceSlug}`);
+        return {
+            workspaceId: created.workspaceId,
+            workspaceSlug: created.workspaceSlug,
+            organizationSlug: created.organizationSlug,
+            gitRepoUrl: created.gitRepoUrl,
+            gitRepoFullName: created.gitRepoFullName ?? null,
+            environments: created.environments,
+        };
+    }
+    /**
+     * oRPC surfaces structured errors as {json: {code, message, ...}} or
+     * {error: {...}}. Extract the message for display; fall back to raw
+     * text when the body isn't JSON.
+     */
+    async extractErrorMessage(res) {
+        try {
+            const body = (await res.clone().json());
+            return body.json?.message || body.error?.message || body.message || '';
+        }
+        catch {
+            try {
+                return await res.text();
+            }
+            catch {
+                return '';
+            }
+        }
+    }
+}

package/dist/util/encryption.d.ts

@@ -14,7 +14,10 @@ export declare function decrypt(encryptedString: string, keyStringHex: string):
  * @param command - The APICommand instance for API calls and logging
  * @param value - The plaintext value to encrypt
  * @param secret - Secret configuration containing key name
- * @param environmentId - Environment ID to fetch encryption key for (empty string for default)
+ * @param environmentName - Environment slug to fetch encryption key for (empty string for default).
+ *   Must be the slug stored in config files (e.g. "production"), not the DB UUID — the encryption
+ *   key config's `environments[].id` holds slugs, and matching against UUIDs silently falls back
+ *   to the default key and produces ciphertext that won't decrypt at runtime.
  * @returns Result<ConfigValue> with encrypted value or error
  */
-export declare function makeConfidentialValue(command: APICommand, value: string, secret: Secret, environmentId: string): Promise<Result<any>>;
+export declare function makeConfidentialValue(command: APICommand, value: string, secret: Secret, environmentName: string): Promise<Result<any>>;

package/dist/util/encryption.js

@@ -53,10 +53,13 @@ export function decrypt(encryptedString, keyStringHex) {
  * @param command - The APICommand instance for API calls and logging
  * @param value - The plaintext value to encrypt
  * @param secret - Secret configuration containing key name
- * @param environmentId - Environment ID to fetch encryption key for (empty string for default)
+ * @param environmentName - Environment slug to fetch encryption key for (empty string for default).
+ *   Must be the slug stored in config files (e.g. "production"), not the DB UUID — the encryption
+ *   key config's `environments[].id` holds slugs, and matching against UUIDs silently falls back
+ *   to the default key and produces ciphertext that won't decrypt at runtime.
  * @returns Result<ConfigValue> with encrypted value or error
  */
-export async function makeConfidentialValue(command, value, secret, environmentId) {
+export async function makeConfidentialValue(command, value, secret, environmentName) {
     // First check if the encryption key exists in metadata
     const metadataRequest = await command.apiClient.post('/api/v1/metadata/list', { workspaceId: command.workspaceId });
     if (!metadataRequest.ok) {
@@ -89,10 +92,12 @@ export async function makeConfidentialValue(command, value, secret, environmentI
     // Find the encryption key for this environment (or default)
     let secretKey;
     let envVar;
-    // Check environment-specific config first
-    if (keyConfig.environments && environmentId) {
+    // Check environment-specific config first. environments[].id is the env slug
+    // (e.g. "production") as stored in the git file — match by slug, not UUID.
+    if (keyConfig.environments && environmentName) {
+        const targetSlug = String(environmentName).toLowerCase();
         /* eslint-disable @typescript-eslint/no-explicit-any */
-        const envConfig = keyConfig.environments.find((env) => String(env.id) === String(environmentId));
+        const envConfig = keyConfig.environments.find((env) => String(env.id).toLowerCase() === targetSlug);
         /* eslint-enable @typescript-eslint/no-explicit-any */
         const ruleValue = envConfig?.rules?.[0]?.value;
         // Check if it's a provided value (env var)
@@ -139,7 +144,7 @@ export async function makeConfidentialValue(command, value, secret, environmentI
         command.verboseLog(`Using literal value from ${secret.keyName} to encrypt secret`);
     }
     if (!secretKey) {
-        return failure(`Failed to create secret: ${secret.keyName} does not have a value configured for environment ${environmentId || 'default'} or default env`, {
+        return failure(`Failed to create secret: ${secret.keyName} does not have a value configured for environment ${environmentName || 'default'} or default env`, {
             phase: 'finding-secret',
         });
     }

package/dist/util/log-levels.d.ts

@@ -0,0 +1,4 @@
+export declare const LOG_LEVELS: readonly ["TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+export declare const LOG_LEVEL_KEY_PREFIX = "log-level.";
+export declare function isLogLevel(value: string): value is LogLevel;

package/dist/util/log-levels.js

@@ -0,0 +1,5 @@
+export const LOG_LEVELS = ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL'];
+export const LOG_LEVEL_KEY_PREFIX = 'log-level.';
+export function isLogLevel(value) {
+    return LOG_LEVELS.includes(value);
+}

package/dist/util/resolve-workspace.d.ts

@@ -0,0 +1,14 @@
+import type { BaseCommand } from '../index.js';
+/**
+ * Resolve the target workspace UUID for commands that don't extend APICommand
+ * (e.g. pull, push — which talk to Gitea, not the oRPC API, but still need to
+ * know which workspace to mint a Gitea token for).
+ *
+ * Handles all three auth paths in the same order as util/get-client.ts:
+ *   1. QUONFIG_API_KEY + QUONFIG_WORKSPACE (or --workspace flag) — CI/headless.
+ *   2. OAuth profile — the default interactive path.
+ *
+ * Mirrors the error messages from get-client.ts so behavior feels identical
+ * whether you're hitting the API directly or going through Gitea.
+ */
+export declare function resolveWorkspaceUuid(command: BaseCommand, flagOverride?: string): Promise<string>;

package/dist/util/resolve-workspace.js

@@ -0,0 +1,75 @@
+import { getApiUrl } from './domain-urls.js';
+import { getValidAccessToken } from './get-valid-token.js';
+import { getActiveProfile, loadAuthConfig, resolveWorkspaceId as resolveOAuthWorkspaceId, } from './token-storage.js';
+const UUID_PATTERN = /^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i;
+/**
+ * Resolve the target workspace UUID for commands that don't extend APICommand
+ * (e.g. pull, push — which talk to Gitea, not the oRPC API, but still need to
+ * know which workspace to mint a Gitea token for).
+ *
+ * Handles all three auth paths in the same order as util/get-client.ts:
+ *   1. QUONFIG_API_KEY + QUONFIG_WORKSPACE (or --workspace flag) — CI/headless.
+ *   2. OAuth profile — the default interactive path.
+ *
+ * Mirrors the error messages from get-client.ts so behavior feels identical
+ * whether you're hitting the API directly or going through Gitea.
+ */
+export async function resolveWorkspaceUuid(command, flagOverride) {
+    const override = flagOverride ?? process.env.QUONFIG_WORKSPACE;
+    const apiKey = process.env.QUONFIG_API_KEY;
+    if (apiKey && apiKey.length > 0) {
+        if (!override) {
+            command.error('QUONFIG_API_KEY is set but QUONFIG_WORKSPACE is not. Set QUONFIG_WORKSPACE=<workspace-slug> or pass --workspace=<slug>. (UUIDs also work.)', { exit: 1 });
+        }
+        if (UUID_PATTERN.test(override)) {
+            command.verboseLog('ApiKey auth', { source: 'uuid', workspaceId: override });
+            return override;
+        }
+        // Slug — resolve via the server since there's no local auth config in CI mode.
+        const jwt = await getValidAccessToken(command.verboseLog);
+        let res;
+        try {
+            res = await fetch(`${getApiUrl()}/api/v1/userWorkspaces/list`, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify({ json: {} }),
+            });
+        }
+        catch (error) {
+            command.error(`Failed to resolve workspace slug "${override}": ${error instanceof Error ? error.message : String(error)}`, { exit: 1 });
+        }
+        if (!res.ok) {
+            command.error(`Failed to resolve workspace slug "${override}" (HTTP ${res.status}). Check that QUONFIG_API_KEY is valid.`, { exit: 1 });
+        }
+        const body = (await res.json());
+        const entries = body.json ?? body ?? [];
+        const match = entries.find((w) => w.workspaceSlug === override);
+        if (!match) {
+            const available = entries.map((w) => w.workspaceSlug).join(', ') || '(none)';
+            command.error(`No workspace with slug "${override}" is accessible with this API key. Available: ${available}.`, { exit: 1 });
+        }
+        command.verboseLog('ApiKey auth', { source: 'slug', slug: override, workspaceId: match.workspaceId });
+        return match.workspaceId;
+    }
+    // OAuth path.
+    const authConfig = await loadAuthConfig();
+    if (!authConfig) {
+        command.error('Not logged in. Run `qfg login` first (or set QUONFIG_API_KEY for CI).', { exit: 401 });
+    }
+    if (override) {
+        const resolved = resolveOAuthWorkspaceId(authConfig, override);
+        if (resolved)
+            return resolved;
+        // Fall back to treating the override as a profile name.
+        const profileData = authConfig.profiles[override];
+        if (profileData?.workspace)
+            return profileData.workspace;
+        command.error(`Workspace "${override}" not found. Run \`qfg workspace switch\` to pick one.`, { exit: 1 });
+    }
+    const activeProfile = getActiveProfile();
+    const profileData = authConfig.profiles[activeProfile] || authConfig.profiles[authConfig.defaultProfile || 'default'];
+    if (!profileData?.workspace) {
+        command.error('No active workspace. Run `qfg login` / `qfg workspace switch`, or set QUONFIG_API_KEY + QUONFIG_WORKSPACE.', { exit: 1 });
+    }
+    return profileData.workspace;
+}