@brass-build/cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,170 @@
+# Instructions for AI coding agents
+
+You are likely an AI coding agent publishing a Brass app you built against
+`@brass-build/client`. This tool is how you ship it and how you pull a
+schema to build against. The [README](./README.md) is the full reference;
+this file is the short path for you.
+
+## Follow your organization's coding instructions first
+
+Before you start building, fetch the organization's own agentic-coding
+instructions and follow them: the conventions it wants every app built on
+Brass to follow (its `AGENTS.md` / `CLAUDE.md`). Run the pull rather than
+deciding up front whether the org has any; nothing loads them for you, and an
+empty result (the org set none) is something you learn by running it, not by
+assuming it. Treat what it returns as an instruction file committed to the
+repo.
+
+```sh
+npx @brass-build/cli agents pull --out AGENTS.md
+```
+
+This writes the current org instructions to the file. Read it and apply it.
+Keep it current one of two ways:
+
+- **Always fetch (freshest):** run the pull at the start of each session and
+  re-read the file, so you are always on the latest instructions. Pull to a
+  gitignored path if you do not want to commit it, or `--stdout` to read the
+  body inline without writing a file at all (status stays on stderr, so
+  stdout is only the instructions).
+- **Cache:** commit the pulled file and refresh it periodically. Add a
+  `CLAUDE.md` whose entire contents are the single line `@AGENTS.md` so
+  Claude Code picks it up too (Claude Code auto-loads `CLAUDE.md`, not
+  `AGENTS.md`); the command prints this reminder after a pull.
+
+The pull needs a signed-in session (`brass login`); a service token is not an
+organization member and cannot read the instructions. If you are not signed
+in, run the sign-in yourself rather than skipping: `brass login --start`,
+relay the printed URL and code to the human, then `brass login --check --wait`
+until it reports approved (it is the same credential you will use to publish).
+[Signing in](#signing-in) covers the whole flow, including what to do while
+you wait for the approval.
+`--org <organizationId>` is only needed when the human belongs to more than
+one organization. An empty result means the organization has set no
+instructions, and there is nothing to follow.
+
+## Signing in
+
+You cannot approve the sign-in, and the human approving it is not watching
+your terminal. Start it, relay the code, then wait for the approval.
+
+```sh
+npx @brass-build/cli login --start          # prints the approval URL + code
+npx @brass-build/cli login --check --wait   # polls until they approve
+```
+
+`--start` prints an approval URL and a short code and exits. Give both to the
+human in your next message, then run `--check --wait`. It polls for up to two
+minutes (`--wait <seconds>` for a different bound) and stores the session the
+moment they approve. A code that lapses is replaced and the new one printed,
+so the sign-in outlives any single code and a session started early is still
+good at publish time.
+
+The session gates your organization's coding conventions, and those shape the
+code you are about to write, so wait for it before you build rather than
+building twice. If you do have work that does not depend on them, the wait
+costs nothing to repeat: a bound reached with the code still approvable
+reports `pending`, and the next `--check --wait` picks the same sign-in back
+up where it left off.
+
+Read the `state` in its `--json` result:
+
+- `approved`: the session is stored, and every later command uses it.
+- `pending`: the code you relayed is still good. Run the check again.
+- `renewed`: the code changed. Relay the new one from the same output.
+- `denied`: the human refused. Ask them why before starting another.
+
+Run `brass login --start` again only when there is nothing in flight; it
+resumes the sign-in already waiting rather than issuing a second code, so a
+half-finished approval still completes. `brass status` reports an in-flight
+sign-in and how long it has left, so you never have to guess.
+
+## Publishing an app you built
+
+Start with `brass status`, and act on the `Next:` line it prints:
+
+```sh
+npx @brass-build/cli status
+```
+
+It reports the credential and app state for this environment and names the
+one command to run next (obtain a credential, create the app on a first
+publish, deploy, or open the live URL). Run it, do what it says, then run it
+again. The steps below are what it walks you through:
+
+1. Build the app to a static bundle (its `brass-app.json` capability
+   manifest must be in the output).
+2. Make sure a credential is available: `BRASS_SERVICE_TOKEN` in the
+   environment (or `--token`) for CI, or a `brass login` session for local
+   development. When `brass status` reports none, run the sign-in yourself,
+   as [Signing in](#signing-in) describes.
+   Starting it, relaying the URL, and checking it through to approved is your
+   step, not a handoff you stop at. (Or the human mints a service token in
+   the dashboard: org Settings, then Service tokens.)
+3. Publish:
+
+   ```sh
+   npx @brass-build/cli publish ./dist
+   ```
+
+   The first run creates the app and writes `.brass/project.json`; commit
+   that so re-runs target the same app. A service token creates the app in
+   its own organization, so no `--org` is needed. If the pipeline does not
+   persist `.brass/project.json` between runs, set a stable `client_token`
+   (a `"client_token"` in `brass-app.json`, or `--client-token`) so the
+   first create is idempotent and re-runs resolve the same app.
+
+Run with `--json` to get the result (`app_id`, `url`) as JSON on stdout for
+your own parsing. A non-zero exit means the publish failed; the reason is on
+stderr.
+
+## Pulling a schema to build against
+
+To interoperate with documents another app or importer produces, do not
+hand-write the schema. Open one of its documents and pull the real body:
+
+```sh
+npx @brass-build/cli schema pull --doc <docId> --out brass-app.json
+```
+
+This writes the schema verbatim into your manifest. Build your types against
+that copy; do not re-approximate it from memory (a mismatched `required`
+shape makes the platform read your app as a different shape). This is a
+development-time step that needs a signed-in session (`brass login`), not a
+service token; if you only have `BRASS_SERVICE_TOKEN`, ask the human to run
+`brass login` or to copy the schema from the document's dashboard page.
+
+## Verifying
+
+`npx @brass-build/cli status` is the check to run before and after a publish:
+it confirms the credential authenticates and reports whether the app is
+deployed, with the next step to take. `npx @brass-build/cli whoami` is the
+narrower check when you only need to confirm the credential works. After a
+publish, open the reported URL to confirm the app loads.
+
+## When a command fails
+
+Read what the error says before drawing a conclusion about the machine you
+are on. The CLI reports the state it observed, and the states have different
+fixes:
+
+- **A 401 or 403** means the credential is expired, missing, or not allowed.
+  A session expires, so `brass login` is the fix; a service token that is
+  rejected needs a valid `BRASS_SERVICE_TOKEN`. A fresh checkout or a fresh
+  container has no session at all, which is the ordinary starting state, not
+  a broken one.
+- **"Network error reaching <url>"** is the only error meaning the request
+  never completed. It names the host it tried.
+- **Any other status** is a fault on the server side. The credential is
+  still good and retrying is reasonable.
+
+An HTTP status coming back at all proves the host answered you. So confirm
+reachability directly before reporting that Brass is unreachable:
+
+```sh
+curl -sS -o /dev/null -w '%{http_code}\n' https://api.brass.build/health
+```
+
+`/health` requires a credential, so an unauthenticated `401` here is a
+reachable API. Run `brass status` for the full credential and app state
+along with the next command to run.

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `@brass-build/cli` are recorded here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+package follows [semantic versioning](https://semver.org/spec/v2.0.0.html).
+While the version is below `1.0.0`, minor releases may introduce breaking
+changes.
+
+## 0.1.0
+
+Initial public release. The `brass` command-line tool publishes apps and
+pulls schemas from a terminal or CI. Ships as an ESM-only package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brass Software LLC
+
+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,172 @@
+# @brass-build/cli
+
+From a terminal or a CI pipeline, the `brass` command publishes a Brass
+app's built bundle and pulls document schemas. It wraps the same data API the
+dashboard uses, authenticated by a token instead of a browser session, so
+the whole publish workflow runs unattended.
+
+This package tracks the platform's `0.1.x` line.
+
+## Install
+
+No install step. Run it with `npx`:
+
+```sh
+npx @brass-build/cli publish ./dist
+```
+
+## Authenticate
+
+Two kinds of credential, for two audiences:
+
+- A **signed-in session** from `brass login` is the developer credential.
+  It opens your browser, you approve once, and the CLI stores the session
+  under `~/.config/brass/`. It authorizes everything, including `schema pull`.
+- A **service token** (mint one in the dashboard: org Settings, then Service
+  tokens) is the CI credential, supplied as `BRASS_SERVICE_TOKEN`. It
+  authorizes `publish` and `whoami`. It is an org-scoped machine identity
+  and, by design, cannot fetch schemas.
+
+```sh
+npx @brass-build/cli login                  # developer: sign in with your browser
+export BRASS_SERVICE_TOKEN=brass_sk_...     # CI: a pipeline secret
+```
+
+`login` opens your browser to an approval page showing a short code, prints
+the same URL and code to the terminal, and completes on its own once you
+approve. Confirm the code on the page matches the one in your terminal, then
+approve. On a machine with no browser (a remote box, an SSH session), open the
+printed URL from any other device.
+
+For automation that cannot hold a command open while you approve (an AI
+agent driving the sign-in), the flow splits in two: `brass login --start`
+prints the approval URL and code and exits immediately, and
+`brass login --check` checks that sign-in, storing the session once you have
+approved. Add `--wait` to poll until you approve, for two minutes by default
+or `--wait <seconds>` for a different bound; a code that lapses inside the
+wait is replaced and the new one printed, so a sign-in started long before it
+is needed still completes. Reaching the bound with the code still good is
+reported as `pending` and exits 0, so the next check picks the same sign-in
+back up. A second `--start` resumes the sign-in already waiting instead of
+issuing a second code, and `--new` overrides that when you have lost the
+first. Both phases honor `--json` for a machine-readable result on stdout.
+
+The CLI picks a credential most-explicit first: `--token <token>`, then
+`BRASS_SERVICE_TOKEN`, then the stored `brass login` session. `brass logout`
+forgets the stored session.
+
+```sh
+export BRASS_SERVICE_TOKEN=brass_sk_...
+npx @brass-build/cli whoami
+```
+
+## Status
+
+`status` reports the credential and app state for the target environment and
+the one command to run next:
+
+```sh
+npx @brass-build/cli status
+```
+
+It confirms whether your credential authenticates, whether an app id is
+resolved for this directory, and whether that app is deployed, then prints a
+`Next:` line naming the exact next step (sign in, publish to create the app,
+deploy, or open the live URL). When a `brass login --start` sign-in is waiting
+for approval, it reports the code, the approval URL, and how long the code has
+left. Run it before a publish to see what will
+happen, and after one to confirm the app is live. `whoami` is the narrower
+check when you only need to know the credential works. Add `--json` for the
+machine-readable result on stdout.
+
+## Publish
+
+`publish` deploys a built static bundle to the app's Brass hosting
+(`https://<slug>.onbrass.app`):
+
+```sh
+npx @brass-build/cli publish ./dist
+```
+
+On the first publish with no app yet, it creates one (using `--name`, or the
+`name` in `brass-app.json`) and records the new app id in `.brass/project.json`
+so later publishes target the same app. Commit that file, or pin the app
+explicitly with `--app <appId>` or `BRASS_APP_ID` for a stateless pipeline.
+
+For a pipeline that stands the app up from scratch and does not persist
+`.brass/project.json` between runs, set a stable `client_token` (a
+`"client_token"` in `brass-app.json`, or `--client-token`). Repeated first
+publishes then resolve the same app instead of creating a duplicate each run.
+A service token creates the app in its own organization, so no `--org` is
+needed.
+
+The command enables hosting if needed, uploads the bundle, waits for it to go
+live, and reports the URL. The platform reads your app's capabilities
+(`opens` / `creates` / `schema`) from the `/.well-known/brass-app.json` you
+serve, so keep that manifest in the bundle.
+
+Flags: `--app`, `--name`, `--org` (organization to own a newly created app;
+defaults to a service token's own org), `--client-token` (stable idempotency
+key for a first create), `--slug` (preferred subdomain), `--manifest`
+(default `brass-app.json`).
+
+## Pull a schema
+
+To build against a shape another app or importer produces, open one of its
+documents and copy its schema into your manifest:
+
+```sh
+npx @brass-build/cli schema pull --doc <docId> --out brass-app.json
+```
+
+This writes the document's schema body verbatim into the manifest's `schema`
+field, preserving everything else. That is the same copy-verbatim step the
+SDK's schema guide describes, done for you. It is a development-time action
+that needs a signed-in session (`brass login`); a service token cannot fetch
+schemas.
+
+## Pull your organization's agent instructions
+
+If your organization manages a shared set of agentic-coding instructions (its
+AGENTS.md / CLAUDE.md), pull the current body into your repo:
+
+```sh
+npx @brass-build/cli agents pull --out AGENTS.md
+```
+
+The instructions are stored once at the organization level (admins edit them
+on the dashboard Settings tab) so every developer's coding agent works from
+one source of truth. The pull writes the body verbatim, so it round-trips
+byte-for-byte with what the dashboard stored. `--org <organizationId>` is
+optional when you belong to a single organization; pass it when you belong to
+more than one. This needs a signed-in session (`brass login`); a service token
+is not an organization member, so it cannot read the instructions.
+
+Pass `--stdout` instead of `--out` to print the instructions to stdout
+without writing a file (status goes to stderr, so stdout carries only the
+body). This is the always-fetch path: a coding agent reads the current
+instructions inline each session and caches nothing.
+
+The default `--out` is `AGENTS.md`, the cross-agent convention that Cursor,
+Codex, and others read. **Claude Code reads `CLAUDE.md`, not `AGENTS.md`**, so
+to use these instructions there either pull straight to it
+(`agents pull --out CLAUDE.md`) or add a `CLAUDE.md` that imports the pulled
+file with a single line, `@AGENTS.md`. The command prints this reminder
+whenever you pull to any file other than `CLAUDE.md`.
+
+## CI example
+
+```yaml
+- run: npm ci && npm run build
+- run: npx @brass-build/cli publish ./dist
+  env:
+    BRASS_SERVICE_TOKEN: ${{ secrets.BRASS_SERVICE_TOKEN }}
+```
+
+The service token creates the app in its own organization on the first run.
+Give `brass-app.json` a stable `"client_token"` so that first create is
+idempotent (repeated runs resolve the same app rather than duplicating it),
+or commit `.brass/project.json` to pin the app id.
+
+Add `--json` to any command to emit the machine-readable result on stdout
+(human status stays on stderr).

package/dist/api.d.ts

@@ -0,0 +1,73 @@
+import type { AuthProvider } from './auth.js';
+export interface BrassSchemaManifest {
+    family: string;
+    streams: Record<string, Record<string, unknown>>;
+}
+export type AppVisibility = 'private' | 'invitee_visible' | 'public';
+export interface AppDetail {
+    app_id: string;
+    name: string;
+    owner_organization_id?: string;
+    visibility?: AppVisibility;
+}
+export interface HostingStatus {
+    enabled: boolean;
+    slug: string | null;
+    url: string | null;
+    deployed: boolean;
+    active_version: string | null;
+    require_access?: boolean;
+}
+export interface HostingUploadUrl {
+    upload_url: string;
+    version_id: string;
+    expires_in: number;
+}
+export type HostingVersionStatus = 'pending' | 'ready' | 'failed';
+export interface HostingVersion {
+    version_id: string;
+    status: HostingVersionStatus;
+    failure_reason?: string;
+    active: boolean;
+    content_hash?: string;
+}
+export interface DocumentStreams {
+    streams: {
+        name: string;
+        schema?: Record<string, unknown>;
+    }[];
+    predicted?: true;
+}
+export interface DocumentTypeSummary {
+    schema_type?: string;
+}
+export interface AgentInstructionsResponse {
+    content: string;
+    updated_at?: string;
+    updated_by?: string;
+}
+export interface OrganizationSummary {
+    organization_id: string;
+    name: string;
+}
+export interface RefreshCapabilitiesResponse {
+    app_id: string;
+    manifest_origin: string;
+    opens: string[];
+    warnings?: string[];
+}
+export declare class BrassApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare class BrassApi {
+    private readonly apiBaseUrl;
+    private readonly auth;
+    constructor(apiBaseUrl: string, auth: AuthProvider);
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    private request;
+}
+export declare function putPresigned(url: string, bytes: Uint8Array, contentType: string): Promise<void>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -0,0 +1,97 @@
+// The HTTP client the commands share: a bearer-authenticated wrapper over
+// the Brass data API, plus the narrow wire types the CLI reads. Wire shapes
+// are declared here (not imported from `@brass-build/client`) so the CLI
+// stays a standalone package with no browser-SDK dependency; the shapes it
+// depends on are small and stable (the `/apps` + hosting surface).
+import { CLI_CLIENT_ID } from './version.js';
+// One error type for every API failure, carrying the HTTP status and the
+// server-authored message so the CLI can render it verbatim (the API returns
+// `{ error: string }` on the 4xx/5xx ladder).
+export class BrassApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'BrassApiError';
+        this.status = status;
+    }
+}
+export class BrassApi {
+    apiBaseUrl;
+    auth;
+    constructor(apiBaseUrl, auth) {
+        this.apiBaseUrl = apiBaseUrl;
+        this.auth = auth;
+    }
+    get(path) {
+        return this.request('GET', path);
+    }
+    post(path, body) {
+        return this.request('POST', path, body);
+    }
+    patch(path, body) {
+        return this.request('PATCH', path, body);
+    }
+    async request(method, path, body) {
+        const headers = {
+            ...(await this.auth.headers()),
+            // Version telemetry; the api Lambda logs it so pinned CI copies
+            // stay visible in the deployed-version distribution.
+            'x-brass-client': CLI_CLIENT_ID,
+        };
+        let init = { method, headers };
+        if (body !== undefined) {
+            headers['content-type'] = 'application/json';
+            init = { ...init, body: JSON.stringify(body) };
+        }
+        let response;
+        try {
+            response = await fetch(`${this.apiBaseUrl}${path}`, init);
+        }
+        catch (cause) {
+            throw new BrassApiError(0, `Network error reaching ${this.apiBaseUrl}: ${String(cause)}`);
+        }
+        if (!response.ok) {
+            throw new BrassApiError(response.status, await errorMessage(response));
+        }
+        if (response.status === 204)
+            return undefined;
+        return (await response.json());
+    }
+}
+// Upload bytes to a presigned S3 URL. Deliberately carries NO Brass headers
+// and no bearer: the presigned signature pins an exact header set, and a
+// stray `authorization` header would break it (the same rule the SDK's
+// `api-headers` module enforces on the document path).
+export async function putPresigned(url, bytes, contentType) {
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'PUT',
+            headers: { 'content-type': contentType },
+            // fflate allocates a plain ArrayBuffer, so narrowing the generic off
+            // `ArrayBufferLike` is sound and satisfies fetch's `BufferSource`
+            // (which pins `ArrayBufferView<ArrayBuffer>`) across lib configs.
+            body: bytes,
+        });
+    }
+    catch (cause) {
+        throw new BrassApiError(0, `Network error uploading the bundle: ${String(cause)}`);
+    }
+    if (!response.ok) {
+        throw new BrassApiError(response.status, `Bundle upload failed (${response.status})`);
+    }
+}
+// Pull the server's `{ error }` message off a failed response, falling back
+// to the bare status when the body is not the expected shape.
+async function errorMessage(response) {
+    try {
+        const body = (await response.json());
+        if (typeof body.error === 'string' && body.error !== '')
+            return body.error;
+    }
+    catch {
+        // Non-JSON body (an edge / gateway error); fall through to the status.
+    }
+    return `Request failed with status ${response.status}`;
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/args.d.ts

@@ -0,0 +1,10 @@
+export interface ParsedArgs {
+    positionals: string[];
+    flags: Record<string, string | true>;
+}
+export declare function unknownFlags(parsed: ParsedArgs): string[];
+export declare function valuelessFlags(parsed: ParsedArgs, names: readonly string[]): string[];
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+export declare function stringFlag(parsed: ParsedArgs, name: string): string | undefined;
+export declare function boolFlag(parsed: ParsedArgs, name: string): boolean;
+//# sourceMappingURL=args.d.ts.map

package/dist/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IAGtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACtC;AAyCD,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAEzD;AAOD,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAErF;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CA6B7D;AAID,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAElE"}

package/dist/args.js

@@ -0,0 +1,94 @@
+// A minimal argv parser: no dependency, and small enough to unit-test the
+// exact precedence the commands rely on. Supports `--flag value`,
+// `--flag=value`, and boolean `--flag`; everything else is a positional.
+// Flags that never take a value, so `brass publish --yes ./dist` parses
+// `./dist` as a positional rather than the value of `--yes`.
+const BOOLEAN_FLAGS = new Set([
+    'json',
+    'yes',
+    'help',
+    'version',
+    'stdout',
+    'start',
+    'check',
+    'new',
+]);
+// Every flag any command reads. A flag outside this set is rejected rather
+// than ignored, because ignoring one silently retargets the invocation: the
+// origin flags default to production, so a misspelled `--api-ur1` publishes an
+// app, or mints a sign-in, against the real platform while naming another
+// stack on the command line.
+const KNOWN_FLAGS = new Set([
+    ...BOOLEAN_FLAGS,
+    'api-url',
+    'app',
+    'auth-url',
+    'client-token',
+    'dashboard-url',
+    'doc',
+    'gate',
+    'manifest',
+    'name',
+    'org',
+    'out',
+    'slug',
+    'token',
+    'visibility',
+    'wait',
+]);
+// The flag names this CLI does not know, in the order given, for an error
+// naming all of them rather than one per run.
+export function unknownFlags(parsed) {
+    return Object.keys(parsed.flags).filter((name) => !KNOWN_FLAGS.has(name));
+}
+// Which of `names` were given without a value (`--api-url --json`, or
+// `--api-url` last on the line). The parser stores those as `true` and
+// `stringFlag` reads that as absent, so an origin flag in this state resolves
+// the production default while the command line names another stack. That is
+// the same silent retarget `unknownFlags` catches for a misspelled name.
+export function valuelessFlags(parsed, names) {
+    return names.filter((name) => parsed.flags[name] === true);
+}
+export function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (arg.startsWith('--')) {
+            const body = arg.slice(2);
+            const eq = body.indexOf('=');
+            if (eq !== -1) {
+                flags[body.slice(0, eq)] = body.slice(eq + 1);
+                continue;
+            }
+            if (BOOLEAN_FLAGS.has(body)) {
+                flags[body] = true;
+                continue;
+            }
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                flags[body] = next;
+                i++;
+            }
+            else {
+                flags[body] = true;
+            }
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return { positionals, flags };
+}
+// Read a flag expected to carry a string value; a bare boolean flag (no
+// value) is treated as absent so `--doc` alone doesn't resolve to `true`.
+export function stringFlag(parsed, name) {
+    const v = parsed.flags[name];
+    return typeof v === 'string' ? v : undefined;
+}
+export function boolFlag(parsed, name) {
+    return parsed.flags[name] === true || typeof parsed.flags[name] === 'string';
+}
+//# sourceMappingURL=args.js.map