@typeship-ax/cli 0.22.0 → 0.24.0

package/AGENTS.md

@@ -1,6 +1,6 @@
-# typeship — agent context
+# Typeship: agent guide
 
-This package contains the generated CLI for **typeship** (API v1.0.0, package v0.22.0).
+Instructions for coding agents that call the Typeship API through this CLI (API version 1.0.0, package version 0.24.0).
 
 Resolve an OpenAPI or GraphQL Spec, diagnose it, and keep every
 selected CLI, MCP, and SDK Target current.
@@ -16,12 +16,10 @@ Examples use Parcel, a fictional delivery service. Replace its domains,
 repository names, and resource identifiers with your own. The hosted
 petstore Spec is a runnable sample.
 
-## Ground rules
-- Maintaining this package: when its repository receives reviewed regeneration pull requests, committed customizations are preserved and edits that overlap a generated change stop for review. Regenerating into a directory replaces its files.
-- A custom file ships only when the package manifest, exports, build, and tests include it. Add a package check for every custom build or test step.
+## Before writing code
+- `api.md` is the command and flag reference; `api.json` is the machine-readable contract: every operation's inputs, outputs, errors, `safety` (`read`, `write`, or `destructive`), and an example. Look up exact names there instead of guessing.
+- `README.md` covers installation and setup.
 - Zero runtime dependencies; the program runs on Node.js 20+ 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.
@@ -29,8 +27,14 @@ petstore Spec is a runnable sample.
 ## 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.
+- `typeship agent-guide --format json` explains the conventions; `typeship help --json` indexes the commands and `typeship help <resource> <command> --json` gives one command's flags; `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.
+
+## Safety
+- Read credentials from the environment or a secret store. Never hard-code them, print them, or put them in URLs or command arguments.
+- Check an operation's `safety` in `api.json` before calling it. Confirm with the user before running a `write` or `destructive` operation they did not ask for.
+- Destructive commands stop for confirmation unless `--force` (or `--yes`) is passed. Pass it only when the user asked for that change.
+- Keep results small: select only the fields you need with `--fields` (CLI).
 
 ## 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`.
+- 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/docs`.

package/README.md

@@ -1,45 +1,28 @@
 # @typeship-ax/cli
 
-CLI for typeship. [API reference](./api.md)
+CLI for the Typeship API. [API reference](./api.md)
 
-Generated from the OpenAPI spec by [typeship](https://typeship.dev).
+Resolve an OpenAPI or GraphQL Spec, diagnose it, and keep every selected CLI, MCP, and SDK Target current.
 
-- **Zero runtime dependencies** — built on the platform `fetch` in Node 20+
-- **Spec-native CLI** — every operation is a command with typed flags, stable JSON, help, and exit codes
-
-## Build from source
-
-Run these commands in the downloaded or cloned package directory:
+## Installation
 
 ```sh
-npm install
-npm run build
-node dist/cli.js --help
+npm install --global @typeship-ax/cli@0.24.0
 ```
 
-Requires Node.js 20+. 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.22.0
-```
+Requires Node.js 20+.
 
-## CLI
+## Usage
 
 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
-node dist/cli.js login # stores a credential (or set TYPESHIP_TOKEN)
-node dist/cli.js organization get
-node dist/cli.js projects list --all # every page, one item per line
-node dist/cli.js help --json # command names, flags, and types
+typeship login # stores a credential (or set TYPESHIP_TOKEN)
+typeship organization get
+typeship projects list --all # every page, one item per line
+typeship help --json # resources and command names; help <resource> <command> --json adds flags
 ```
 
-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.
@@ -49,9 +32,13 @@ CLI conventions:
 
 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.
 
+Headers the spec does not declare: `--header "Name: value"` (repeatable) or `TYPESHIP_HEADERS` (a JSON object, or one `Name: value` per line). They are sent on every request and replace any header of the same name the CLI would send.
+
 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:
 
 - `typeship init` configures credentials and repository agent instructions.
 - `typeship docs search <term> --json`, `typeship doctor`, and `typeship help --json` cover discovery and diagnostics.
+
+Generated from the OpenAPI spec by [Typeship](https://typeship.dev).