@eightstate/escli 0.5.0

package/CONVENTIONS.md

@@ -0,0 +1,59 @@
+# escli conventions
+
+## Command grammar
+
+- Prefer `noun verb [args] [options]`.
+- Root leaves are allowed only for established top-level services: `version`, `models`, `search`, `fetch`, `research`, `social`, `usage`.
+- Namespaces (`auth`, `audio`, `docs`, `image`) must have a bare-topic command that emits usage, exits `2`, and uses the envelope in JSON mode.
+- Aliases are declared in `src-ts/lib/registry.ts`, not ad hoc in command code.
+
+## Machine envelope
+
+All JSON output uses:
+
+```ts
+{ ok: true, data, error: null, meta }
+{ ok: false, data: null, error, meta }
+```
+
+`meta.schema_version` is `"1"`. `meta.warnings` is always an array. `error.code` is a dotted `ErrorCode` from `@eightstate/contracts/errors`.
+
+## stdout / stderr
+
+- `--json`: stdout is exactly one envelope plus newline.
+- `--quiet`: suppress diagnostics/progress.
+- Human output may use stdout for data and stderr for diagnostics, but must be deterministic under `NO_COLOR` and non-TTY.
+- Command and service modules must not write directly to stdout/stderr. Use `src-ts/io/**`; ESLint enforces this.
+
+## TTY and color
+
+Renderers must degrade cleanly for non-TTY, `NO_COLOR=1`, and `CI=1`. No JSON parser should ever need to strip ANSI or progress text from stdout.
+
+## Exit codes
+
+- `0` success
+- `1` non-retryable error
+- `2` usage/validation
+- `4` auth/permission
+- `5` not found
+- `8` transient/retryable
+
+Runtime exit mapping must match `packages/contracts/src/failure-taxonomy.ts`.
+
+## Error codes
+
+Use lowercase dotted codes with a namespace prefix (`auth.required`, `docs.fetch_failed`, `api.error`). Do not add a code without adding taxonomy coverage, registry coverage, and contract tests.
+
+Current usage decision: `usage.fetch_failed` is 404/not-found only. Other usage 4xx failures use `api.error` unless they have a more specific auth/rate-limit code.
+
+## Enforcement
+
+- Runner owns parse errors, validation errors, envelope construction, and exit codes.
+- Commands return typed data or throw `EscliError`.
+- `pnpm lint:bypass:check` proves direct process IO, `process.exit`, `console`, and legacy `{success: ...}` payload bypasses fail lint.
+- Test endpoint env vars must be guarded by inline `typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__` checks so prod `--define __ESCLI_TEST__:false` dead-code-eliminates `ESCLI_TEST_*` strings.
+- `pnpm check:prod-symbols` must report `ESCLI_TEST_ symbol count: 0` for the prod binary.
+
+## Manifest
+
+`buildManifest()` walks the command registry and validates against `ManifestSchema`. Root `--schema`/`--describe` returns all commands; `--schema <namespace>` and `--schema <namespace> <verb>` return scoped command sets by command-id prefix.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eightstate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# escli
+
+`escli` is the Eightstate command line for agent-friendly AI workflows: auth, models, usage, docs, fetch, search, social search, deep research, audio transcription, and image generation/editing.
+
+Version `0.5.0` is the TypeScript/Bun cutover. The CLI now ships as native binaries and uses the stable `{ok,data,error,meta}` JSON envelope.
+
+## Install
+
+### macOS / Linux
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/eight-state/eightstate/main/cli/install.sh | bash
+```
+
+Set `ESCLI_VERSION`, `ESCLI_RELEASE_BASE_URL`, or `ESCLI_INSTALL_DIR` to override the release or install location. Default install dir: `$HOME/.local/bin`.
+
+### Windows PowerShell
+
+```powershell
+irm https://raw.githubusercontent.com/eight-state/eightstate/main/cli/install.ps1 | iex
+```
+
+Default install dir: `$env:LOCALAPPDATA\eightstate\bin`.
+
+### npm
+
+```bash
+pnpm add -g @eightstate/escli
+# or npm install -g @eightstate/escli
+```
+
+The native archive installers are the primary zero-runtime path. npm is supported for JS environments.
+
+## Quickstart
+
+```bash
+escli auth login
+escli models
+escli docs get react "useEffect cleanup" --tokens 5000
+escli search "Cloudflare Workers 2026 limits"
+escli fetch https://example.com --objective "pricing"
+escli research "market map for residential HVAC software" -o report.md
+escli audio transcribe meeting.mp3 --speakers
+escli image generate "a sunset over the ocean" --open
+```
+
+Short aliases include `i g`/`i e`, `a s`, `d g`, `au t`, `m`, `s`, `f`, `r`, and `u`.
+
+## JSON envelope
+
+Use `--json --quiet` for automation. stdout is exactly one JSON object plus a trailing newline.
+
+Success:
+
+```json
+{"ok":true,"data":{},"error":null,"meta":{"schema_version":"1","escli_version":"0.5.0","command":"version","warnings":[]}}
+```
+
+Failure:
+
+```json
+{"ok":false,"data":null,"error":{"code":"auth.required","message":"not authenticated","remediation":{"command":"escli auth login"}},"meta":{"schema_version":"1","escli_version":"0.5.0","command":"models","warnings":[]}}
+```
+
+This replaces the pre-0.5 `{success,...}` shape.
+
+## Exit codes
+
+| Code | Meaning |
+|---:|---|
+| 0 | success |
+| 1 | non-retryable service/client error |
+| 2 | usage, parsing, validation, missing argument |
+| 4 | auth or permission failure |
+| 5 | not found |
+| 8 | transient/retryable network, rate-limit, timeout, or service-unavailable failure |
+
+## Manifest and schema
+
+```bash
+escli --describe                 # compact full manifest
+escli --schema                   # full manifest with schemas
+escli --schema docs              # docs namespace only
+escli --schema docs get          # docs get leaf only
+```
+
+Manifest output is contract-validated and includes command ids, aliases, args, flags, examples, error codes, input schemas, and output envelope schemas.
+
+## Command shape
+
+Commands use `noun verb [args] [options]`. Root leaves (`models`, `search`, `fetch`, `research`, `social`, `usage`, `version`) remain single-token. Namespaced topics (`auth`, `audio`, `docs`, `image`) print a usage envelope and exit `2` when called without a verb.
+
+## Environment
+
+Common variables:
+
+| Variable | Description |
+|---|---|
+| `ESCLI_API_KEY` | API key override |
+| `ESCLI_BASE_URL` | OpenAI-compatible endpoint override |
+| `ESCLI_GATE_URL` | Eightstate gate endpoint override |
+| `ESCLI_CONFIG_DIR` | config directory, default `~/.escli` |
+| `ESCLI_CACHE_DIR` | cache directory |
+| service keys | `OPENAI_API_KEY`, `PARALLEL_API_KEY`, `ASSEMBLYAI_API_KEY`, `TAVILY_API_KEY`, `CONTEXT7_API_KEY` |
+
+Credentials are stored in `config.json` under `ESCLI_CONFIG_DIR` with owner-only permissions where supported.

package/RELEASE-NOTES-0.5.0.md

@@ -0,0 +1,34 @@
+# escli 0.5.0 release notes
+
+## Breaking: JSON envelope
+
+`--json` output changed from the legacy Python `{success: ...}` shape to the stable agent envelope:
+
+```json
+{"ok":true,"data":{},"error":null,"meta":{"schema_version":"1","escli_version":"0.5.0","command":"version","warnings":[]}}
+{"ok":false,"data":null,"error":{"code":"auth.required","message":"not authenticated"},"meta":{"schema_version":"1","escli_version":"0.5.0","command":"models","warnings":[]}}
+```
+
+Consumers must read `ok`, then branch on `data` or `error.code`.
+
+## Install change
+
+Installers no longer install Python or `uv`. They download native release archives, verify `checksums.txt`, and install `escli` into:
+
+- macOS/Linux: `${ESCLI_INSTALL_DIR:-$HOME/.local/bin}`
+- Windows: `$env:ESCLI_INSTALL_DIR` or `$env:LOCALAPPDATA\eightstate\bin`
+
+The installer warns if another `escli` shadows the installed binary on PATH.
+
+## Python removed
+
+The Python CLI package (`src/escli/**`, `pyproject.toml`, and the root `./escli` shadow script) is removed from this branch. Parity test files remain in the repo, but skip cleanly when the Python oracle is absent.
+
+## Command polish
+
+- Added `auth` topic alias `a`, including `a s`, `a login`, `a profiles`, `a switch`, and `a logout` forms.
+- Added bare-topic usage stubs for `auth`, `audio`, and `docs`.
+- Scoped `--schema <namespace>` and `--schema <namespace> <verb>` manifests.
+- `usage.fetch_failed` is now reserved for usage 404/not-found; other usage 4xx failures report `api.error`.
+- Production binaries are built with `__ESCLI_TEST__:false` and checked to contain zero `ESCLI_TEST_*` strings.
+- `research --processors` now intentionally returns a compact processor list: `data.processors[]` entries are `{name}` only. The previous descriptive fields (`variant`, `latency`, `description`, `max_fields`) were removed from the 0.5.0 JSON contract.

package/dist/base-command.js

@@ -0,0 +1,166 @@
+import { Command, Flags, Errors } from '@oclif/core';
+import { z } from 'zod';
+import { EnvelopeSchema } from '@eightstate/contracts/envelope';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { ExitCodes } from '@eightstate/contracts/exit-codes';
+import { getCommandMetadata } from './lib/command-metadata.js';
+import { buildErrorEnvelope, meta } from './lib/envelope.js';
+import { EscliError } from './lib/escli-error.js';
+import { globalFlags } from './lib/globals.js';
+import { writeStdout, renderKeyValue } from './io/io.js';
+export class BaseCommand extends Command {
+    static emitsJsonEnvelope = false;
+    static baseFlags = {
+        ...globalFlags,
+        json: Flags.boolean({ description: 'Format output as json.', helpGroup: 'GLOBAL' }),
+    };
+    humanOutputHandled = false;
+    async parseFlags(command) {
+        const { flags } = await this.parse(command);
+        return flags;
+    }
+    async run() {
+        const start = Date.now();
+        let flags = {};
+        try {
+            const manifestMode = this.manifestMode();
+            if (manifestMode) {
+                this.parsed = true;
+                await this.emitManifest(manifestMode === 'describe');
+                return;
+            }
+            flags = await this.parseFlags(this.ctor);
+            const data = await this.execute();
+            const envelope = this.successEnvelope(data, Date.now() - start);
+            if (flags.json || this.ctor.emitsJsonEnvelope) {
+                await this.emitJson(envelope);
+            }
+            else {
+                await this.emitHuman(data);
+            }
+        }
+        catch (error) {
+            this.parsed = true;
+            const escliError = toEscliError(error);
+            process.exitCode = escliError.exitCode;
+            const envelope = this.errorEnvelope(escliError, Date.now() - start);
+            await this.emitJson(envelope);
+        }
+    }
+    successEnvelope(data, durationMs) {
+        const metadata = getCommandMetadata(this.id ?? 'unknown');
+        const serviceMeta = this.serviceMeta(data);
+        const parsedData = metadata ? safeInternalParse(metadata.dataSchema, data) : data;
+        const envelope = {
+            ok: true,
+            data: parsedData,
+            error: null,
+            meta: { ...this.meta(durationMs), ...serviceMeta },
+        };
+        return (metadata ? safeInternalParse(EnvelopeSchema(metadata.dataSchema), envelope) : envelope);
+    }
+    errorEnvelope(error, durationMs) {
+        return buildErrorEnvelope(this.id ?? 'unknown', this.config.version, error, durationMs);
+    }
+    meta(durationMs) {
+        return meta(this.id ?? 'unknown', this.config.version, durationMs);
+    }
+    serviceMeta(data) {
+        if (!data || typeof data !== 'object' || Array.isArray(data))
+            return {};
+        return Object.fromEntries(Object.entries(data).filter(([key, value]) => (key.endsWith('_count') || ['credits', 'elapsed_seconds'].includes(key)) && (typeof value === 'number' || value === null)));
+    }
+    async emitJson(envelope) {
+        await writeStdout(`${JSON.stringify(envelope)}\n`);
+    }
+    manifestMode() {
+        for (let index = 0; index < this.argv.length; index += 1) {
+            const token = this.argv[index];
+            if (!token?.startsWith('--'))
+                return undefined;
+            if (token === '--describe' || token.startsWith('--describe='))
+                return 'describe';
+            if (token === '--schema' && (!this.argv[index + 1] || this.argv[index + 1]?.startsWith('--')))
+                return 'schema';
+            if (token.startsWith('--schema='))
+                return 'schema';
+            if (['--api-key', '--base-url', '--timeout'].includes(token) && this.argv[index + 1] && !this.argv[index + 1]?.startsWith('--'))
+                index += 1;
+        }
+        return undefined;
+    }
+    async emitHuman(data) {
+        if (this.humanOutputHandled)
+            return;
+        const metadata = getCommandMetadata(this.id ?? 'unknown');
+        if (metadata?.render) {
+            await writeStdout(`${await metadata.render(data)}\n`);
+            return;
+        }
+        if (data === null || data === undefined) {
+            await writeStdout('\n');
+            return;
+        }
+        if (typeof data !== 'object' || Array.isArray(data)) {
+            await writeStdout(`${typeof data === 'string' ? data : JSON.stringify(data, null, 2)}\n`);
+            return;
+        }
+        const entries = Object.entries(data);
+        const hasNested = entries.some(([, value]) => value !== null && (typeof value === 'object' || Array.isArray(value)));
+        if (hasNested) {
+            await writeStdout(`${JSON.stringify(data, null, 2)}\n`);
+            return;
+        }
+        await writeStdout(`${renderKeyValue(entries.map(([k, v]) => [k, v === null || v === undefined ? '' : String(v)]))}\n`);
+    }
+    async emitManifest(compact) {
+        const { buildManifest } = await import('./lib/manifest.js');
+        await writeStdout(`${JSON.stringify(buildManifest(compact, this.argv.includes('--root-manifest') ? undefined : this.id ?? undefined))}\n`);
+    }
+}
+function safeInternalParse(schema, value) {
+    try {
+        return schema.parse(value);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new EscliError('internal data validation failed', { code: ErrorCode.Internal, exitCode: ExitCodes.Error, details: error.issues });
+        }
+        throw error;
+    }
+}
+function toEscliError(error) {
+    if (error instanceof EscliError)
+        return error;
+    if (error instanceof z.ZodError) {
+        return new EscliError('input validation failed', { code: ErrorCode.ValidationFailed, exitCode: ExitCodes.Usage, details: error.issues });
+    }
+    if (error instanceof Errors.ExitError) {
+        return new EscliError(error.message, { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage, details: { oclif_exit: error.oclif?.exit } });
+    }
+    if (error instanceof Errors.CLIError) {
+        return oclifErrorToEscliError(error);
+    }
+    if (error instanceof Error)
+        return new EscliError(error.message, { code: ErrorCode.Internal });
+    return new EscliError('unknown error', { code: ErrorCode.Unknown, details: error });
+}
+function oclifErrorToEscliError(error) {
+    const code = classifyOclifUsageError(error);
+    return new EscliError(cleanOclifMessage(error.message), { code, exitCode: ExitCodes.Usage, details: { oclif_exit: error.oclif?.exit } });
+}
+function classifyOclifUsageError(error) {
+    const name = error.constructor.name;
+    const message = error.message;
+    if (name === 'NonExistentFlagsError' || message.startsWith('Nonexistent flag') || message.startsWith('Unexpected flag'))
+        return ErrorCode.UsageUnknownFlag;
+    if (name === 'RequiredArgsError' || message.startsWith('Missing ') || message.includes('expects a value'))
+        return ErrorCode.UsageRequired;
+    if (message.includes('command ') && message.includes(' not found'))
+        return ErrorCode.UsageUnknownCommand;
+    return ErrorCode.UsageInvalid;
+}
+function cleanOclifMessage(message) {
+    return message.replace(/\nSee more help with --help$/u, '');
+}
+//# sourceMappingURL=base-command.js.map

package/dist/commands/audio/get.js

@@ -0,0 +1,39 @@
+import { Args, Flags } from '@oclif/core';
+import { z } from 'zod';
+import { BaseCommand } from '../../base-command.js';
+import { writeStdout } from '../../io/io.js';
+import { getAudioTranscript } from '../../services/audio.js';
+import { AudioTranscriptSchema } from './transcribe.js';
+import { ErrorCode } from '@eightstate/contracts/errors';
+export const AudioGetDataSchema = z.union([
+    AudioTranscriptSchema,
+    z.object({ output: z.string(), format: z.enum(['text', 'json', 'srt', 'vtt']), id: z.string().optional() }).passthrough(),
+    z.object({ path: z.string(), format: z.enum(['text', 'json', 'srt', 'vtt']), id: z.string().optional() }).passthrough(),
+]);
+export default class AudioGet extends BaseCommand {
+    static errors = [ErrorCode.UsageRequired, ErrorCode.UsageUnknownFlag, ErrorCode.AuthRequired, ErrorCode.GateCredentialUnavailable, ErrorCode.ApiUnauthorized, ErrorCode.ApiForbidden, ErrorCode.ApiRateLimited, ErrorCode.ApiError, ErrorCode.NetworkError, ErrorCode.NetworkTimeout, ErrorCode.ServiceUnavailable, ErrorCode.GateInvalidResponse, ErrorCode.FileWriteFailed, ErrorCode.AudioTranscriptionFailed, ErrorCode.AudioTranscriptNotFound];
+    static summary = 'Fetch a completed transcript';
+    static description = 'Fetch a completed AssemblyAI transcript as text, JSON, SRT, or VTT.';
+    static examples = ['<%= config.bin %> audio get tr_xxx', '<%= config.bin %> audio get tr_xxx --format srt', '<%= config.bin %> audio get tr_xxx -o transcript.txt'];
+    static aliases = ['audio g', 'au get', 'au g'];
+    static flags = {
+        format: Flags.string({ description: 'Output format.', options: ['text', 'json', 'srt', 'vtt'], default: 'text' }),
+        output: Flags.string({ char: 'o', description: 'Output file.' }),
+    };
+    static args = {
+        transcript_id: Args.string({ description: 'Transcript ID.', required: true }),
+    };
+    static enableJsonFlag = true;
+    static strict = true;
+    async execute() {
+        const { args, flags } = await this.parse(AudioGet);
+        const data = await getAudioTranscript(args.transcript_id, flags.format, flags.output);
+        if (!flags.json) {
+            if ('output' in data && typeof data.output === 'string')
+                await writeStdout(`${data.output}${data.output.endsWith('\n') ? '' : '\n'}`);
+            this.humanOutputHandled = true;
+        }
+        return data;
+    }
+}
+//# sourceMappingURL=get.js.map

package/dist/commands/audio/index.js

@@ -0,0 +1,18 @@
+import { BaseCommand } from '../../base-command.js';
+import { buildUsageError } from '../../lib/envelope.js';
+import { ErrorCode } from '@eightstate/contracts/errors';
+export default class AudioTopic extends BaseCommand {
+    static errors = [ErrorCode.UsageInvalid];
+    static summary = 'Transcribe and manage audio transcripts';
+    static description = 'Use audio transcribe, audio status, audio get, or audio list.';
+    static examples = ['<%= config.bin %> audio transcribe meeting.mp3', '<%= config.bin %> audio status tr_xxx', '<%= config.bin %> audio list'];
+    static aliases = ['au'];
+    static flags = {};
+    static args = {};
+    static enableJsonFlag = true;
+    static strict = true;
+    async execute() {
+        throw buildUsageError('usage: escli audio <transcribe|status|get|list>');
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/audio/list.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { BaseCommand } from '../../base-command.js';
+import { writeStdout } from '../../io/io.js';
+import { listAudioTranscripts } from '../../services/audio.js';
+import { AudioTranscriptSchema } from './transcribe.js';
+import { ErrorCode } from '@eightstate/contracts/errors';
+export const AudioListDataSchema = z.object({
+    transcripts: z.array(AudioTranscriptSchema),
+    count: z.number().int().nonnegative(),
+});
+export default class AudioList extends BaseCommand {
+    static errors = [ErrorCode.AuthRequired, ErrorCode.GateCredentialUnavailable, ErrorCode.ApiUnauthorized, ErrorCode.ApiForbidden, ErrorCode.ApiRateLimited, ErrorCode.ApiError, ErrorCode.NetworkError, ErrorCode.NetworkTimeout, ErrorCode.ServiceUnavailable, ErrorCode.GateInvalidResponse];
+    static summary = 'List recent transcripts';
+    static description = 'List recent AssemblyAI transcripts.';
+    static examples = ['<%= config.bin %> audio list', '<%= config.bin %> --json audio list'];
+    static aliases = ['audio ls', 'au list', 'au ls'];
+    static flags = {};
+    static args = {};
+    static enableJsonFlag = true;
+    static strict = true;
+    async execute() {
+        const { flags } = await this.parse(AudioList);
+        const data = await listAudioTranscripts();
+        if (!flags.json) {
+            if (data.transcripts.length === 0)
+                await writeStdout('  No transcripts found.\n');
+            else {
+                const lines = [`\n  ${'ID'.padEnd(40)} ${'STATUS'.padEnd(12)} CREATED`, `  ${'─'.repeat(70)}`];
+                for (const transcript of data.transcripts)
+                    lines.push(`  ${transcript.id.padEnd(40)} ${String(transcript.status ?? '').padEnd(12)} ${String(transcript.created ?? '')}`);
+                lines.push('');
+                await writeStdout(`${lines.join('\n')}\n`);
+            }
+            this.humanOutputHandled = true;
+        }
+        return data;
+    }
+}
+//# sourceMappingURL=list.js.map

package/dist/commands/audio/status.js

@@ -0,0 +1,34 @@
+import { Args } from '@oclif/core';
+import { z } from 'zod';
+import { BaseCommand } from '../../base-command.js';
+import { writeStdout } from '../../io/io.js';
+import { getAudioStatus } from '../../services/audio.js';
+import { ErrorCode } from '@eightstate/contracts/errors';
+export const AudioStatusDataSchema = z.object({
+    id: z.string(),
+    status: z.string(),
+    error: z.string().nullable().optional(),
+});
+export default class AudioStatus extends BaseCommand {
+    static errors = [ErrorCode.UsageRequired, ErrorCode.UsageUnknownFlag, ErrorCode.AuthRequired, ErrorCode.GateCredentialUnavailable, ErrorCode.ApiUnauthorized, ErrorCode.ApiForbidden, ErrorCode.ApiRateLimited, ErrorCode.ApiError, ErrorCode.NetworkError, ErrorCode.NetworkTimeout, ErrorCode.ServiceUnavailable, ErrorCode.GateInvalidResponse, ErrorCode.AudioTranscriptNotFound];
+    static summary = 'Check transcript status';
+    static description = 'Fetch an AssemblyAI transcript job status.';
+    static examples = ['<%= config.bin %> audio status tr_xxx', '<%= config.bin %> --json audio status tr_xxx'];
+    static aliases = ['audio s', 'au status', 'au s'];
+    static flags = {};
+    static args = {
+        transcript_id: Args.string({ description: 'Transcript ID.', required: true }),
+    };
+    static enableJsonFlag = true;
+    static strict = true;
+    async execute() {
+        const { args, flags } = await this.parse(AudioStatus);
+        const data = await getAudioStatus(args.transcript_id);
+        if (!flags.json) {
+            await writeStdout(`  ${data.id}: ${data.status}${data.error ? `\n  error: ${data.error}` : ''}\n`);
+            this.humanOutputHandled = true;
+        }
+        return data;
+    }
+}
+//# sourceMappingURL=status.js.map

package/dist/commands/audio/transcribe.js

@@ -0,0 +1,99 @@
+import { Args, Flags } from '@oclif/core';
+import { z } from 'zod';
+import { BaseCommand } from '../../base-command.js';
+import { writeStdout } from '../../io/io.js';
+import { formatTranscriptText, transcribeAudio } from '../../services/audio.js';
+import { ErrorCode } from '@eightstate/contracts/errors';
+export const AudioWordSchema = z.object({ text: z.string() }).passthrough();
+export const AudioUtteranceSchema = z.object({ speaker: z.string().optional(), text: z.string() }).passthrough();
+export const AudioTranscriptSchema = z.object({
+    id: z.string(),
+    status: z.string().optional(),
+    text: z.string().optional(),
+    words: z.array(AudioWordSchema).optional(),
+    utterances: z.array(AudioUtteranceSchema).optional(),
+}).passthrough();
+export const AudioTranscribeDataSchema = z.union([
+    z.object({
+        id: z.string(),
+        elapsed_seconds: z.number().nonnegative(),
+        text: z.string(),
+        speakers: z.number().int().nonnegative(),
+        words: z.array(AudioWordSchema),
+        utterances: z.array(AudioUtteranceSchema),
+    }).passthrough(),
+    AudioTranscriptSchema,
+    z.object({ output: z.string(), format: z.enum(['text', 'json', 'srt', 'vtt']), id: z.string().optional() }).passthrough(),
+    z.object({ path: z.string(), format: z.enum(['text', 'json', 'srt', 'vtt']), id: z.string().optional() }).passthrough(),
+]);
+export default class AudioTranscribe extends BaseCommand {
+    static errors = [ErrorCode.UsageRequired, ErrorCode.UsageUnknownFlag, ErrorCode.AuthRequired, ErrorCode.GateCredentialUnavailable, ErrorCode.ApiUnauthorized, ErrorCode.ApiForbidden, ErrorCode.ApiRateLimited, ErrorCode.ApiError, ErrorCode.NetworkError, ErrorCode.NetworkTimeout, ErrorCode.ServiceUnavailable, ErrorCode.GateInvalidResponse, ErrorCode.FileNotFound, ErrorCode.FileReadFailed, ErrorCode.FileWriteFailed, ErrorCode.AudioInputMissing, ErrorCode.AudioUploadFailed, ErrorCode.AudioTranscriptionFailed, ErrorCode.AudioTranscriptNotFound];
+    static summary = 'Transcribe an audio file or URL';
+    static description = 'Upload a local audio file or submit an audio URL to AssemblyAI, poll to completion, and return transcript output.';
+    static examples = ['<%= config.bin %> audio transcribe meeting.mp3 --speakers', '<%= config.bin %> audio transcribe https://example.com/audio.mp3 --speakers-expected 3', '<%= config.bin %> --json audio transcribe file.mp3'];
+    static aliases = ['audio t', 'au transcribe', 'au t'];
+    static flags = {
+        output: Flags.string({ char: 'o', description: 'Output file.' }),
+        format: Flags.string({ description: 'Output format.', options: ['text', 'json', 'srt', 'vtt'], default: 'text' }),
+        speakers: Flags.boolean({ description: 'Enable speaker diarization.', default: false }),
+        'speakers-expected': Flags.integer({ description: 'Expected speaker count.' }),
+        'speaker-names': Flags.string({ description: 'Identify speakers by name, comma-separated.' }),
+        sentiment: Flags.boolean({ description: 'Enable sentiment analysis.', default: false }),
+        chapters: Flags.boolean({ description: 'Enable auto chapters.', default: false }),
+        entities: Flags.boolean({ description: 'Enable entity detection.', default: false }),
+        summarize: Flags.boolean({ description: 'Enable summarization.', default: false }),
+        highlights: Flags.boolean({ description: 'Enable auto highlights.', default: false }),
+        topics: Flags.boolean({ description: 'Enable topic detection.', default: false }),
+        'content-safety': Flags.boolean({ description: 'Enable content safety detection.', default: false }),
+        language: Flags.string({ description: 'Language code. Defaults to auto-detection.' }),
+        'dual-channel': Flags.boolean({ description: 'Enable dual-channel transcription.', default: false }),
+        multichannel: Flags.boolean({ description: 'Enable multichannel transcription.', default: false }),
+        'word-boost': Flags.string({ description: 'Boost accuracy for comma-separated words.' }),
+        disfluencies: Flags.boolean({ description: 'Include filler words.', default: false }),
+        'filter-profanity': Flags.boolean({ description: 'Filter profanity.', default: false }),
+        'redact-pii': Flags.boolean({ description: 'Redact personally identifiable information.', default: false }),
+    };
+    static args = {
+        source: Args.string({ description: 'Audio file path or URL.', required: true }),
+    };
+    static enableJsonFlag = true;
+    static strict = true;
+    async execute() {
+        const { args, flags } = await this.parse(AudioTranscribe);
+        const options = {
+            source: args.source,
+            output: flags.output,
+            format: flags.format,
+            language: flags.language,
+            speakers: flags.speakers,
+            speakersExpected: flags['speakers-expected'],
+            speakerNames: flags['speaker-names'],
+            sentiment: flags.sentiment,
+            chapters: flags.chapters,
+            entities: flags.entities,
+            summarize: flags.summarize,
+            highlights: flags.highlights,
+            topics: flags.topics,
+            contentSafety: flags['content-safety'],
+            dualChannel: flags['dual-channel'],
+            multichannel: flags.multichannel,
+            wordBoost: flags['word-boost'],
+            disfluencies: flags.disfluencies,
+            filterProfanity: flags['filter-profanity'],
+            redactPii: flags['redact-pii'],
+            quiet: flags.quiet,
+        };
+        const data = await transcribeAudio(options);
+        if (!flags.json) {
+            if ('output' in data && typeof data.output === 'string')
+                await writeStdout(`${data.output}${data.output.endsWith('\n') ? '' : '\n'}`);
+            else if ('path' in data && typeof data.path === 'string')
+                await writeStdout(flags.quiet ? `${data.path}\n` : '');
+            else
+                await writeStdout(`${formatTranscriptText(data)}\n`);
+            this.humanOutputHandled = true;
+        }
+        return data;
+    }
+}
+//# sourceMappingURL=transcribe.js.map

package/dist/commands/auth/index.js

@@ -0,0 +1,18 @@
+import { BaseCommand } from '../../base-command.js';
+import { buildUsageError } from '../../lib/envelope.js';
+import { ErrorCode } from '@eightstate/contracts/errors';
+export default class AuthTopic extends BaseCommand {
+    static errors = [ErrorCode.UsageInvalid];
+    static summary = 'Authenticate and manage profiles';
+    static description = 'Use auth login, auth status, auth profiles, auth switch, or auth logout.';
+    static examples = ['<%= config.bin %> auth status', '<%= config.bin %> auth login', '<%= config.bin %> auth profiles'];
+    static aliases = ['a'];
+    static flags = {};
+    static args = {};
+    static enableJsonFlag = true;
+    static strict = true;
+    async execute() {
+        throw buildUsageError('usage: escli auth <login|status|profiles|switch|logout>');
+    }
+}
+//# sourceMappingURL=index.js.map