bunqueue 2.8.0 → 2.8.2

package/dist/application/queueManager.js

@@ -509,6 +509,15 @@ export class QueueManager {
     releaseClientJobs(clientId) {
         return lockMgr.releaseClientJobs(clientId, this.contextFactory.getLockContext());
     }
+    /**
+     * Force-release client tracking without acquiring queue locks. Last-resort
+     * fallback when releaseClientJobs has exhausted its retry budget — clears
+     * the clientJobs map entry to prevent leaks and resets job heartbeats so
+     * the stall detector recovers orphaned active jobs on its next tick.
+     */
+    forceReleaseClientJobs(clientId) {
+        return lockMgr.forceReleaseClientJobs(clientId, this.contextFactory.getLockContext());
+    }
     // ============ Query Operations ============
     async getJob(jobId) {
         return queryOps.getJob(jobId, this.contextFactory.getQueryContext());
@@ -630,6 +639,55 @@ export class QueueManager {
     }
     obliterate(queue) {
         queueControl.obliterateQueue(queue, this.contextFactory.getQueueControlContext());
+        dlqOps.purgeDlqJobs(queue, this.contextFactory.getDlqContext());
+        // obliterateQueue() clears the waiting/delayed shard only. Active jobs in
+        // processingShards, plus completed/result/log/lock state in global indexes,
+        // plus SQLite rows, all survive unless we purge them here.
+        const toDrop = new Set();
+        for (const [jid, loc] of this.jobIndex) {
+            if (loc.type === 'processing') {
+                const job = this.processingShards[loc.shardIdx]?.get(jid);
+                if (job?.queue === queue)
+                    toDrop.add(jid);
+            }
+            else if (loc.queueName === queue) {
+                toDrop.add(jid);
+            }
+        }
+        for (const jid of toDrop) {
+            const loc = this.jobIndex.get(jid);
+            if (loc?.type === 'processing') {
+                this.processingShards[loc.shardIdx]?.delete(jid);
+            }
+            this.jobIndex.delete(jid);
+            this.completedJobs.delete(jid);
+            this.completedJobsData.delete(jid);
+            this.jobResults.delete(jid);
+            this.jobLogs.delete(jid);
+            this.jobLocks.delete(jid);
+            this.failedChildrenValues.delete(jid);
+            this.ignoredChildrenFailures.delete(jid);
+            this.pendingDepChecks.delete(jid);
+            this.stalledCandidates.delete(jid);
+            this.repeatChain.delete(jid);
+            this.storage?.deleteJob(jid);
+        }
+        // repeatChain maps oldId → newId; drop rows whose value is now a ghost.
+        const chainKeysToDelete = [];
+        for (const [oldId, newId] of this.repeatChain) {
+            if (toDrop.has(newId))
+                chainKeysToDelete.push(oldId);
+        }
+        for (const oldId of chainKeysToDelete)
+            this.repeatChain.delete(oldId);
+        // Drop customId → JobId mappings that point at a dropped job
+        const customIdsToDelete = [];
+        for (const [cid, jid] of this.customIdMap.entries()) {
+            if (toDrop.has(jid))
+                customIdsToDelete.push(cid);
+        }
+        for (const cid of customIdsToDelete)
+            this.customIdMap.delete(cid);
         this.unregisterQueueName(queue);
         this.dashboardEmit?.('queue:obliterated', { queue });
         this.dashboardEmit?.('queue:removed', { queue });
@@ -773,8 +831,8 @@ export class QueueManager {
     async updateJobData(jobId, data) {
         return jobMgmt.updateJobData(jobId, data, this.contextFactory.getJobMgmtContext());
     }
-    async changePriority(jobId, priority) {
-        return jobMgmt.changeJobPriority(jobId, priority, this.contextFactory.getJobMgmtContext());
+    async changePriority(jobId, priority, lifo) {
+        return jobMgmt.changeJobPriority(jobId, priority, this.contextFactory.getJobMgmtContext(), lifo);
     }
     async promote(jobId) {
         return jobMgmt.promoteJob(jobId, this.contextFactory.getJobMgmtContext());
@@ -783,8 +841,14 @@ export class QueueManager {
         return jobMgmt.moveJobToDelayed(jobId, delay, this.contextFactory.getJobMgmtContext());
     }
     async changeDelay(jobId, delay) {
-        // Change delay is essentially moving to delayed with new delay
-        return jobMgmt.moveJobToDelayed(jobId, delay, this.contextFactory.getJobMgmtContext());
+        const ctx = this.contextFactory.getJobMgmtContext();
+        const loc = ctx.jobIndex.get(jobId);
+        // Jobs already in queue (waiting/delayed): mutate runAt in place
+        if (loc?.type === 'queue') {
+            return jobTransitions.changeWaitingDelay(jobId, delay, ctx);
+        }
+        // Active/processing jobs: move back to queue with new delay
+        return jobMgmt.moveJobToDelayed(jobId, delay, ctx);
     }
     async moveActiveToWait(jobId) {
         return jobTransitions.moveActiveToWait(jobId, this.contextFactory.getJobMgmtContext());
@@ -933,6 +997,15 @@ export class QueueManager {
         return this.shards;
     }
     onJobCompleted(completedId) {
+        // Release flow-failure tracking once a parent job reaches terminal completion
+        // (AUDIT H8). The parent consumes these values via getFailedChildrenValues()/
+        // getIgnoredChildrenFailures() while it is processing (before it acks), so by the
+        // time it completes they are no longer needed. Keyed by parentId; obliterate()
+        // and shutdown() clear them too. Without this, every parent completion that
+        // involved a failed child with continueParentOnFailure / ignoreDependencyOnFailure
+        // leaked an entry permanently.
+        this.failedChildrenValues.delete(completedId);
+        this.ignoredChildrenFailures.delete(completedId);
         this.pendingDepChecks.add(completedId);
         this.scheduleDependencyFlush();
         void this.checkFlowCompleted(completedId);
@@ -1003,7 +1076,11 @@ export class QueueManager {
             const entry = shard.addToDlq(parentJob, "unknown" /* FailureReason.Unknown */, failError);
             this.jobIndex.set(parentId, { type: 'dlq', queueName: parentJob.queue });
             this.storage?.saveDlqEntry(entry);
+            this.storage?.deleteJob(parentId);
         });
+        // Parent reached a terminal (DLQ) state — release its flow-failure tracking.
+        this.failedChildrenValues.delete(parentId);
+        this.ignoredChildrenFailures.delete(parentId);
         // Broadcast failed event for parent
         this.eventsManager.broadcast({
             eventType: 'failed',
@@ -1035,7 +1112,7 @@ export class QueueManager {
         }
     }
     /**
-     * continueParentOnFailure: move parent to queue immediately when a child fails.
+     * continueParentOnFailure: move parent to queue when a child fails.
      * Stores the failure info for getFailedChildrenValues().
      */
     async continueParentOnChildFailure(childJob, error) {
@@ -1054,6 +1131,19 @@ export class QueueManager {
         existing[childKey] = error ?? 'unknown error';
         this.failedChildrenValues.set(parentId, existing);
         const idx = shardIndex(parentJob.queue);
+        await this.promoteParentAfterChildFailure(parentId, parentJob, idx);
+    }
+    /**
+     * Move a flow parent from its waiting state into the run queue after a child failure
+     * (continueParentOnFailure / last-dependency resolution). Deferred to the next tick
+     * so the failed child's worker batch drains first — the parent is then picked up on
+     * a subsequent poll rather than racing to completion in the same synchronous cascade.
+     */
+    async promoteParentAfterChildFailure(parentId, parentJob, idx) {
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, 0);
+            timer.unref?.();
+        });
         let promoted = false;
         await withWriteLock(this.shardLocks[idx], () => {
             // TOCTOU guard
@@ -1113,7 +1203,9 @@ export class QueueManager {
             this.ignoredChildrenFailures.set(parentId, existing);
         }
         const idx = shardIndex(parentJob.queue);
-        let promoted = false;
+        // Remove the failed child from the parent's pending deps synchronously so
+        // dependency tracking stays consistent; defer only the promotion decision.
+        let readyToPromote = false;
         await withWriteLock(this.shardLocks[idx], () => {
             if (this.jobIndex.get(parentId)?.type !== 'queue')
                 return;
@@ -1127,28 +1219,13 @@ export class QueueManager {
                 parentJob.dependsOn.splice(depIndex, 1);
                 shard.unregisterDependencies(parentId, [childJob.id]);
             }
-            // If no more pending deps, promote parent
-            const allDone = parentJob.dependsOn.length === 0 ||
-                parentJob.dependsOn.every((dep) => this.completedJobs.has(dep));
-            if (allDone) {
-                shard.waitingDeps.delete(parentId);
-                const now = Date.now();
-                parentJob.runAt = now;
-                shard.getQueue(parentJob.queue).push(parentJob);
-                shard.incrementQueued(parentId, false, parentJob.createdAt, parentJob.queue, now);
-                this.jobIndex.set(parentId, { type: 'queue', shardIdx: idx, queueName: parentJob.queue });
-                shard.notify();
-                promoted = true;
-            }
+            // If no more pending deps, the parent is ready to be promoted
+            readyToPromote =
+                parentJob.dependsOn.length === 0 ||
+                    parentJob.dependsOn.every((dep) => this.completedJobs.has(dep));
         });
-        if (promoted) {
-            this.eventsManager.broadcast({
-                eventType: 'waiting',
-                queue: parentJob.queue,
-                jobId: parentId,
-                timestamp: Date.now(),
-                prev: 'waiting-children',
-            });
+        if (readyToPromote) {
+            await this.promoteParentAfterChildFailure(parentId, parentJob, idx);
         }
     }
     /**
@@ -1353,6 +1430,8 @@ export class QueueManager {
         this.stalledCandidates.clear();
         this.clientJobs.clear();
         this.repeatChain.clear();
+        this.failedChildrenValues.clear();
+        this.ignoredChildrenFailures.clear();
         for (const shard of this.processingShards)
             shard.clear();
         for (const shard of this.shards) {
@@ -1364,4 +1443,3 @@ export class QueueManager {
         }
     }
 }
-//# sourceMappingURL=queueManager.js.map

package/dist/application/stallDetection.d.ts

@@ -8,4 +8,3 @@ import type { BackgroundContext } from './types';
  * Uses two-phase detection to prevent false positives
  */
 export declare function checkStalledJobs(ctx: BackgroundContext): void;
-//# sourceMappingURL=stallDetection.d.ts.map

package/dist/application/stallDetection.js

@@ -115,6 +115,7 @@ function moveStalliedJobToDlq(job, ctx, shard, procIdx, _idx) {
     const entry = shard.addToDlq(job, "stalled" /* FailureReason.Stalled */, `Job stalled ${job.stallCount + 1} times`);
     ctx.jobIndex.set(job.id, { type: 'dlq', queueName: job.queue });
     ctx.storage?.saveDlqEntry(entry);
+    ctx.storage?.deleteJob(job.id);
 }
 /** Retry stalled job */
 function retryStalliedJob(job, ctx, shard, procIdx, idx) {
@@ -150,4 +151,3 @@ function retryStalliedJob(job, ctx, shard, procIdx, idx) {
     ctx.jobIndex.set(job.id, { type: 'queue', shardIdx: idx, queueName: job.queue });
     ctx.storage?.updateForRetry(job);
 }
-//# sourceMappingURL=stallDetection.js.map

package/dist/application/statsManager.d.ts

@@ -81,4 +81,3 @@ export declare function getQueueJobCounts(queueName: string, ctx: StatsContext):
  * Use after large batch operations or when memory pressure is high.
  */
 export declare function compactMemory(ctx: StatsContext): void;
-//# sourceMappingURL=statsManager.d.ts.map

package/dist/application/statsManager.js

@@ -225,4 +225,3 @@ export function compactMemory(ctx) {
         }
     }
 }
-//# sourceMappingURL=statsManager.js.map

package/dist/application/taskErrorTracking.d.ts

@@ -20,4 +20,3 @@ export declare function handleTaskSuccess(taskName: string): void;
  * Get error statistics for monitoring
  */
 export declare function getTaskErrorStats(): Record<string, TaskErrorState>;
-//# sourceMappingURL=taskErrorTracking.d.ts.map

package/dist/application/taskErrorTracking.js

@@ -47,4 +47,3 @@ export function handleTaskSuccess(taskName) {
 export function getTaskErrorStats() {
     return { ...taskErrors };
 }
-//# sourceMappingURL=taskErrorTracking.js.map

package/dist/application/throughputTracker.d.ts

@@ -32,4 +32,3 @@ export declare class ThroughputTracker {
 /** Global singleton */
 export declare const throughputTracker: ThroughputTracker;
 export {};
-//# sourceMappingURL=throughputTracker.d.ts.map

package/dist/application/throughputTracker.js

@@ -50,4 +50,3 @@ export class ThroughputTracker {
 }
 /** Global singleton */
 export const throughputTracker = new ThroughputTracker();
-//# sourceMappingURL=throughputTracker.js.map

package/dist/application/types.d.ts

@@ -7,7 +7,7 @@ import type { JobLogEntry } from '../domain/types/worker';
 import type { Shard } from '../domain/queue/shard';
 import type { SqliteStorage } from '../infrastructure/persistence/sqlite';
 import type { RWLock } from '../shared/lock';
-import type { LRUMap, BoundedSet, SetLike } from '../shared/lru';
+import type { LRUMap, BoundedSet, BoundedMap, SetLike } from '../shared/lru';
 import type { EventsManager } from './eventsManager';
 import type { WebhookManager } from './webhookManager';
 import type { WorkerManager } from './workerManager';
@@ -102,6 +102,7 @@ export interface BackgroundContext extends QueueManagerState {
     dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
     workerManager: WorkerManager;
     monitoringState: MonitoringState;
+    completedJobsData: BoundedMap<JobId, Job>;
 }
 /** Context for stats operations */
 export interface StatsContext {
@@ -136,4 +137,3 @@ export interface StatsContext {
         totalFailed: bigint;
     }>;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/application/types.js

@@ -13,4 +13,3 @@ export const DEFAULT_CONFIG = {
     stallCheckMs: 5_000,
     dlqMaintenanceMs: 60_000,
 };
-//# sourceMappingURL=types.js.map

package/dist/application/webhookManager.d.ts

@@ -45,4 +45,3 @@ export declare class WebhookManager {
         enabled: number;
     };
 }
-//# sourceMappingURL=webhookManager.d.ts.map

package/dist/application/webhookManager.js

@@ -155,4 +155,3 @@ export class WebhookManager {
         };
     }
 }
-//# sourceMappingURL=webhookManager.js.map

package/dist/application/workerManager.d.ts

@@ -58,4 +58,3 @@ export declare class WorkerManager {
         activeJobs: number;
     };
 }
-//# sourceMappingURL=workerManager.d.ts.map

package/dist/application/workerManager.js

@@ -217,4 +217,3 @@ export class WorkerManager {
         };
     }
 }
-//# sourceMappingURL=workerManager.js.map

package/dist/cli/client.d.ts

@@ -15,4 +15,3 @@ export interface ClientOptions {
 }
 /** Execute a CLI command against the server */
 export declare function executeCommand(command: string, args: string[], options: ClientOptions): Promise<void>;
-//# sourceMappingURL=client.d.ts.map

package/dist/cli/client.js

@@ -135,11 +135,24 @@ export async function executeCommand(command, args, options) {
         }
         // Execute command
         const response = await sendCommand(connection.socket, cmd);
+        // Extract subcommand (first positional arg) so the formatter can pick the
+        // right verb for batch-id responses (queue drain → "Drained", dlq retry
+        // → "Retried", etc.). Falls back to undefined when not applicable.
+        const subcommand = typeof args[0] === 'string' && !args[0].startsWith('-') ? args[0] : undefined;
         if (!response.ok) {
-            console.error(formatOutput(response, command, options.json));
+            console.error(formatOutput(response, command, options.json, subcommand));
             process.exit(1);
         }
-        console.log(formatOutput(response, command, options.json));
+        console.log(formatOutput(response, command, options.json, subcommand));
+        // Worker registrations are tied to the TCP connection — the server
+        // auto-unregisters when the client disconnects (see tcp.ts close handler).
+        // The one-shot CLI command opens, registers, and immediately closes, so
+        // by the time control returns to the shell the worker is already gone.
+        // Emit a warning to stderr so users don't expect persistence.
+        if (cmd.cmd === 'RegisterWorker' && !options.json && response.ok) {
+            process.stderr.write('Warning: worker registration is transient and expires when this CLI process exits. ' +
+                'For persistent workers, run a long-lived process via the SDK (Worker class) or `bunqueue start` with --processor.\n');
+        }
     }
     catch (err) {
         const message = err instanceof Error ? err.message : 'Unknown error';
@@ -192,4 +205,3 @@ async function buildCommand(command, args) {
             return null;
     }
 }
-//# sourceMappingURL=client.js.map

package/dist/cli/commands/backup.d.ts

@@ -17,4 +17,3 @@ export declare function executeBackupCommand(args: string[]): Promise<BackupComm
  * Check if a command is a backup command
  */
 export declare function isBackupCommand(cmd: string): boolean;
-//# sourceMappingURL=backup.d.ts.map

package/dist/cli/commands/backup.js

@@ -140,4 +140,3 @@ function executeBackupStatus(manager) {
 export function isBackupCommand(cmd) {
     return cmd === 'backup';
 }
-//# sourceMappingURL=backup.js.map

package/dist/cli/commands/core.d.ts

@@ -4,4 +4,3 @@
  */
 /** Build a core command from CLI args */
 export declare function buildCoreCommand(command: string, args: string[]): Record<string, unknown>;
-//# sourceMappingURL=core.d.ts.map

package/dist/cli/commands/core.js

@@ -157,4 +157,3 @@ function buildFail(args) {
         cmd.error = values.error;
     return cmd;
 }
-//# sourceMappingURL=core.js.map

package/dist/cli/commands/cron.d.ts

@@ -4,4 +4,3 @@
  */
 /** Build a cron subcommand */
 export declare function buildCronCommand(args: string[]): Record<string, unknown>;
-//# sourceMappingURL=cron.d.ts.map

package/dist/cli/commands/cron.js

@@ -72,4 +72,3 @@ function buildCronDelete(args) {
     const name = requireArg(args, 0, 'name');
     return { cmd: 'CronDelete', name };
 }
-//# sourceMappingURL=cron.js.map

package/dist/cli/commands/dlq.d.ts

@@ -4,4 +4,3 @@
  */
 /** Build a DLQ subcommand */
 export declare function buildDlqCommand(args: string[]): Record<string, unknown>;
-//# sourceMappingURL=dlq.d.ts.map

package/dist/cli/commands/dlq.js

@@ -63,4 +63,3 @@ function buildDlqPurge(args) {
     const queue = requireArg(args, 0, 'queue');
     return { cmd: 'PurgeDlq', queue };
 }
-//# sourceMappingURL=dlq.js.map

package/dist/cli/commands/doctor.d.ts

@@ -3,4 +3,3 @@
  * Checks client/server version, connectivity, health, and queue state
  */
 export declare function runDoctor(host: string, httpPort: number): Promise<void>;
-//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/commands/doctor.js

@@ -126,4 +126,3 @@ export async function runDoctor(host, httpPort) {
     }
     process.exit(issues > 0 ? 1 : 0);
 }
-//# sourceMappingURL=doctor.js.map

package/dist/cli/commands/job.d.ts

@@ -4,4 +4,3 @@
  */
 /** Build a job subcommand */
 export declare function buildJobCommand(args: string[]): Record<string, unknown>;
-//# sourceMappingURL=job.d.ts.map

package/dist/cli/commands/job.js

@@ -155,4 +155,3 @@ function buildWaitJob(args) {
         cmd.timeout = timeout;
     return cmd;
 }
-//# sourceMappingURL=job.js.map

package/dist/cli/commands/monitor.d.ts

@@ -4,4 +4,3 @@
  */
 /** Build a monitoring command */
 export declare function buildMonitorCommand(command: string): Record<string, unknown>;
-//# sourceMappingURL=monitor.d.ts.map

package/dist/cli/commands/monitor.js

@@ -18,4 +18,3 @@ export function buildMonitorCommand(command) {
             return { cmd: 'Stats' };
     }
 }
-//# sourceMappingURL=monitor.js.map

package/dist/cli/commands/queue.d.ts

@@ -4,4 +4,3 @@
  */
 /** Build a queue subcommand */
 export declare function buildQueueCommand(args: string[]): Record<string, unknown>;
-//# sourceMappingURL=queue.d.ts.map

package/dist/cli/commands/queue.js

@@ -131,4 +131,3 @@ function buildIsPaused(args) {
     const queue = requireArg(args, 0, 'queue');
     return { cmd: 'IsPaused', queue };
 }
-//# sourceMappingURL=queue.js.map

package/dist/cli/commands/rateLimit.d.ts

@@ -4,4 +4,3 @@
  */
 /** Build a rate-limit or concurrency command */
 export declare function buildRateLimitCommand(command: string, args: string[]): Record<string, unknown>;
-//# sourceMappingURL=rateLimit.d.ts.map

package/dist/cli/commands/rateLimit.js

@@ -64,4 +64,3 @@ function buildConcurrencyClear(args) {
     const queue = requireArg(args, 0, 'queue');
     return { cmd: 'ClearConcurrency', queue };
 }
-//# sourceMappingURL=rateLimit.js.map

package/dist/cli/commands/server.d.ts

@@ -4,4 +4,3 @@
  */
 /** Run the server */
 export declare function runServer(args: string[], showHelp: boolean): Promise<void>;
-//# sourceMappingURL=server.d.ts.map

package/dist/cli/commands/server.js

@@ -182,4 +182,3 @@ ${dim}────────────────────────
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
 }
-//# sourceMappingURL=server.js.map

package/dist/cli/commands/types.d.ts

@@ -14,4 +14,3 @@ export declare function parseJsonArg(value: string, name: string): unknown;
 export declare function parseNumberArg(value: string | undefined, name: string): number | undefined;
 /** Parse job ID argument (UUIDs, numeric IDs, or custom IDs) */
 export declare function parseBigIntArg(value: string, name: string): string;
-//# sourceMappingURL=types.d.ts.map

package/dist/cli/commands/types.js

@@ -43,4 +43,3 @@ export function parseBigIntArg(value, name) {
     }
     return value;
 }
-//# sourceMappingURL=types.js.map

package/dist/cli/commands/webhook.d.ts

@@ -4,4 +4,3 @@
  */
 /** Build a webhook subcommand */
 export declare function buildWebhookCommand(args: string[]): Record<string, unknown>;
-//# sourceMappingURL=webhook.d.ts.map

package/dist/cli/commands/webhook.js

@@ -83,4 +83,3 @@ function buildRemoveWebhook(args) {
     const webhookId = requireArg(args, 0, 'webhookId');
     return { cmd: 'RemoveWebhook', webhookId };
 }
-//# sourceMappingURL=webhook.js.map

package/dist/cli/commands/worker.d.ts

@@ -4,4 +4,3 @@
  */
 /** Build a worker subcommand */
 export declare function buildWorkerCommand(args: string[]): Record<string, unknown>;
-//# sourceMappingURL=worker.d.ts.map

package/dist/cli/commands/worker.js

@@ -49,4 +49,3 @@ function buildUnregisterWorker(args) {
     const workerId = requireArg(args, 0, 'workerId');
     return { cmd: 'UnregisterWorker', workerId };
 }
-//# sourceMappingURL=worker.js.map

package/dist/cli/help.d.ts

@@ -11,4 +11,3 @@ export declare function printServerHelp(): void;
 export declare function printPushHelp(): void;
 /** Print cron add help */
 export declare function printCronAddHelp(): void;
-//# sourceMappingURL=help.d.ts.map

package/dist/cli/help.js

@@ -189,4 +189,3 @@ Examples:
   bunqueue cron add health-check -q monitoring -d '{}' -e 60000
 `);
 }
-//# sourceMappingURL=help.js.map

package/dist/cli/index.d.ts

@@ -20,4 +20,3 @@ export declare function parseGlobalOptions(): {
 /** Main CLI entry */
 export declare function main(): Promise<void>;
 export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -10,6 +10,31 @@ import { isBackupCommand, executeBackupCommand } from './commands/backup';
 import { runDoctor } from './commands/doctor';
 import { VERSION } from '../shared/version';
 import { resolveToken } from '../client/resolveToken';
+/**
+ * Resolve TCP port from env when not set via --port flag.
+ * Priority: explicit CLI flag (caller-checked) > TCP_PORT (server's primary var)
+ *          > BUNQUEUE_TCP_PORT > BQ_TCP_PORT. Reads TCP_PORT first so users
+ * running both server and client in the same shell with TCP_PORT=X get
+ * consistent behavior — same var binds the server AND routes the client.
+ */
+function resolveEnvPort(currentPort) {
+    const envPort = Bun.env.TCP_PORT ?? Bun.env.BUNQUEUE_TCP_PORT ?? Bun.env.BQ_TCP_PORT;
+    if (!envPort)
+        return currentPort;
+    const parsed = parseInt(envPort, 10);
+    if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
+        console.warn(`Warning: Invalid env port "${envPort}". Using ${currentPort}.`);
+        return currentPort;
+    }
+    return parsed;
+}
+/**
+ * Resolve host from env when not set via --host flag.
+ * Priority: HOST (server's primary var) > BUNQUEUE_HOST > BQ_HOST.
+ */
+function resolveEnvHost(currentHost) {
+    return Bun.env.HOST ?? Bun.env.BUNQUEUE_HOST ?? Bun.env.BQ_HOST ?? currentHost;
+}
 /** Parse global options from process.argv */
 export function parseGlobalOptions() {
     const allArgs = process.argv.slice(2);
@@ -54,10 +79,10 @@ export function parseGlobalOptions() {
         else if (arg === '--json') {
             json = true;
         }
-        else if (arg === '--help') {
+        else if (arg === '--help' || arg === '-h') {
             help = true;
         }
-        else if (arg === '--version') {
+        else if (arg === '--version' || arg === '-v') {
             version = true;
         }
         else if (arg.startsWith('--host=')) {
@@ -107,6 +132,10 @@ export function parseGlobalOptions() {
     // Fall back to environment variables for token if not set via CLI flag
     // Priority: --token flag > BQ_TOKEN > BUNQUEUE_TOKEN
     token = resolveToken(token);
+    if (!portExplicit)
+        port = resolveEnvPort(port);
+    if (!hostExplicit)
+        host = resolveEnvHost(host);
     return {
         options: { host, port, token, json, help, version },
         commandArgs,
@@ -222,4 +251,3 @@ if (import.meta.main) {
         process.exit(1);
     });
 }
-//# sourceMappingURL=index.js.map

package/dist/cli/output.d.ts

@@ -3,7 +3,6 @@
  * Formats command responses for terminal display
  */
 /** Main output formatter */
-export declare function formatOutput(response: Record<string, unknown>, command: string, asJson: boolean): string;
+export declare function formatOutput(response: Record<string, unknown>, command: string, asJson: boolean, subcommand?: string): string;
 /** Format error message */
 export declare function formatError(message: string, asJson: boolean): string;
-//# sourceMappingURL=output.d.ts.map