@typeship-ax/cli 0.8.0 → 0.10.0

package/AGENTS.md

@@ -0,0 +1,31 @@
+# typeship — agent context
+
+This package contains the generated CLI for **typeship** (API v1.0.0, package v0.10.0).
+
+Resolve an OpenAPI or GraphQL Definition, diagnose it, and keep every
+selected SDK, CLI, and MCP Target current.
+
+Every operation but one requires a bearer credential: an organization
+API key from the console, or an OAuth access token carrying the operation's
+read, generate, or write capability and the organization selected during
+consent. OAuth grants cannot switch organizations after consent. A browser
+session is not a credential for this API. The exception is POST /generate,
+which works anonymously with the free plan's limits.
+
+## Ground rules
+- Typeship owns the files it generates. Change the API definition, generation settings, or definition patches, then regenerate those files. Repository delivery preserves files outside its generated-file ownership manifest; preserving a file does not add it to the package's exports, build, or tests.
+- Zero runtime dependencies; the program runs on Node.js 18+ and platform `fetch`.
+- `api.md` is the command and flag reference; `api.json` is the machine-readable operation, schema, safety, and example contract. Read them before guessing.
+- Start with the local build or installation instructions in `README.md`. Generation does not publish a registry package.
+
+## Authentication
+- Bearer token: set the `TYPESHIP_TOKEN` environment variable.
+
+## Using the CLI
+- `typeship <resource> <command>` calls an API operation; `typeship docs search <term> --json` finds operations and guides as structured data; `typeship docs <resource> <command>` gives a concise contract and example (add `--schema` for full schemas or `--json` for the machine contract).
+- Path parameters are positional; other inputs are flags. JSON goes to stdout and exit codes are 0/1/2. Errors are one JSON envelope on stderr: `{status, issues: [{code, message}], next_steps, detail}`; branch on `issues[].code`. Every operation classified as destructive requires `--force` (or `--yes`).
+- `typeship agent-guide --format json` explains the conventions; `typeship help --json` is the command surface as data; `typeship doctor` checks the setup. Read `typeship init --help` before setup: it can store credentials and update agent instructions. Choose the scope the task requires.
+
+## Documentation
+- The reference for this exact package: `api.md` (offline, always current with the code).
+- Conceptual guides live on the docs site. For questions about how the API's concepts fit together (flows, ordering, environments), fetch `https://typeship.dev/llms-full.txt` and read the relevant sections; `https://typeship.dev/llms.txt` is the page index. Relative links in the spec resolve against `https://typeship.dev`.

package/README.md

@@ -4,13 +4,27 @@ CLI for typeship. [API reference](./api.md)
 
 Generated from the OpenAPI spec by [typeship](https://typeship.dev). Change the spec or generation settings, then regenerate; generated files are not hand-edited.
 
-- **Zero runtime dependencies** — built on the platform `fetch` (Node 18+, browsers, edge runtimes)
+- **Zero runtime dependencies** — built on the platform `fetch` in Node 18+
 - **Spec-native CLI** — every operation is a command with typed flags, stable JSON, help, and exit codes
 
-## Install
+## Build from source
+
+Run these commands in the downloaded or cloned package directory:
 
 ```sh
-npm install @typeship-ax/cli
+npm install
+npm run build
+node dist/cli.js --help
+```
+
+Requires Node.js 18+. The package is ESM.
+
+## Install a published package
+
+Generation does not publish a package. Before using the registry command below, confirm `name` and `version` in `package.json`, publish under a name you control, and verify that release is available on npm.
+
+```sh
+npm install --global @typeship-ax/cli@0.10.0
 ```
 
 ## CLI
@@ -18,13 +32,14 @@ npm install @typeship-ax/cli
 The package ships `typeship`, a command for every API operation. API commands write JSON to stdout; discovery commands offer `--json`. Exit codes 0/1/2 mean success, request failure, and invalid usage.
 
 ```sh
-npm install -g @typeship-ax/cli
-typeship login                      # stores a credential (or set TYPESHIP_TOKEN)
-typeship projects list
-typeship projects list --all | jq -r '.id'   # every page, one item per line
-typeship <resource> <command> --help     # flags, types, an example
+node dist/cli.js login # stores a credential (or set TYPESHIP_TOKEN)
+node dist/cli.js account retrieve
+node dist/cli.js projects list --all # every page, one item per line
+node dist/cli.js help --json # command names, flags, and types
 ```
 
+These examples run from the package directory. After a global installation, use `typeship` in place of `node dist/cli.js`.
+
 CLI conventions:
 
 - Path parameters are positional; query and body fields are flags named after their wire fields.
@@ -32,7 +47,9 @@ CLI conventions:
 - `--fields id,name` projects results. `--all` streams paginated results as NDJSON.
 - Destructive commands require confirmation or `--force`. Piped errors are stable JSON on stderr.
 
-Auth: `typeship login` stores a credential under `~/.config/typeship/`; the environment (`TYPESHIP_TOKEN`) and flags (`--token`) win over it. `TYPESHIP_BASE_URL` / `--base-url` pick the endpoint.
+Auth: `typeship login` stores a credential under `~/.config/typeship/profiles/default/`; the environment (`TYPESHIP_TOKEN`) and flags (`--token`) win over it. `TYPESHIP_BASE_URL` / `--base-url` pick the endpoint.
+
+Use `typeship login --profile work` for a separate login, `typeship auth use work` to select it, and `typeship auth profiles` to list profiles without exposing tokens. Selection follows `--profile`, then `TYPESHIP_PROFILE`, then the saved selection, then `default`. Profiles isolate saved settings and credentials; an API or environment change requires another login before using the saved credential.
 
 Useful commands: