API
Use dedicated commands for everyday workflows.crewship api exposes the
embedded OpenAPI contract and provides authenticated HTTP access to endpoints
that do not have a dedicated command. The catalog belongs to the CLI build;
a newer or older server can have a different contract. Server authorization and
approval gates apply to every request.
crewship api operations [search]
Search paths, operation IDs, summaries, and tags without contacting a server.
Results are sorted by path and method. Human output shows the method and path. JSON/YAML/NDJSON include operation_id,
method, path, and requires_yes; quiet output prints operation IDs.
crewship api schema [operation-id | METHOD path]
Print the complete embedded OpenAPI document, or a document containing one
operation and its transitively referenced component schemas. Selection uses the
literal path template, including braces. No authentication or network is needed. Shell completion suggests operation IDs,
HTTP methods, and schema paths.
crewship api request METHOD PATH
Send one request through the active profile, server, token, and workspace.
Paths are relative to that server. Absolute URLs, authority overrides, fragments,
traversal segments, and unfilled {parameters} are rejected. Use concrete IDs
in request paths. Query values are encoded; repeated keys are preserved.
JSON responses respect
--format json|yaml|ndjson, preserving integer precision
in JSON. Empty successful responses produce no output. Non-JSON responses require
--output. Error responses use the normal structured stderr and classified exit
codes; failed downloads preserve the original destination file. Redirects are
refused, including redirects on the same server.
--dry-run checks request options, but does not read or validate the body, resolve
workspace slugs, predict authorization, or promise the request will succeed.
--yes acknowledges the HTTP method; it grants no additional server permissions.
Keep secrets in input files or stdin rather than command arguments. Response
contents can contain sensitive data; protect saved output accordingly.
The generic request command does not replace interactive OAuth, WebSocket, or
live event-stream commands. Multipart requests require an explicitly prepared
body and matching content type. Input validation checks JSON syntax, not the
operation’s JSON Schema. Consult the schema and prefer a dedicated command where
one exists.
Agent workflow
- Discover a focused command tree with
crewship commands agent --format json. - For API-level work, find the operation with
crewship api operations agents --format json. - Inspect its inputs with
crewship api schema GET /api/v1/agents --format json. - Read first; preview mutation options with
--dry-run, then execute an authorized mutation with--yes. - Use the exit code and stderr envelope to handle failures. Do not blindly retry mutations.