cosin

# Cosin CLI Use `cosin` to call the COS API and COS-backed skills from the terminal. ## What the CLI does `cosin` now accepts only relative paths. There are three request styles: 1. `skills` Calls `https://skills.bankofuniverse.org/skills` directly and prints the upstream body directly. 2. Normal COS API paths such as `/v1/me` These are sent directly to the COS API host. 3. Skill paths under `/cos/...` These are converted internally into x402 pay-and-call requests: - keeps the same request path - builds the target URL from `SKILLS_BASE_URL` - sends that target URL to `POST /agent/pay-and-call` on the COS API host Users should not pass absolute URLs to the CLI anymore. ## Gather inputs Collect these inputs before running the CLI: - A COS bearer token for `--key` - An HTTP method - A relative path starting with `/` - Optional JSON for `--json` - Optional repeatable headers for `--header` or `-H` - Optional `--base-url` override for normal COS API calls Ask for the token if the user has not provided one. Treat it as sensitive. ## Protect credentials - Treat the `--key` value as sensitive - Do not print, commit, or hardcode the token - Keep the token in the command line argument, not in repo files ## Run the CLI Use one of these command shapes: ```sh cosin --key <token> <METHOD> <PATH> [--json '<json>'] [--header 'Name: value'] [--base-url <url>] cosin --key <token> agent [status|me] [--base-url <url>] cosin --key <token> skills ``` Important flags: - `--key <token>` for the required bearer token - `--json <json>` for an optional JSON request body - `--header 'Name: value'` or `-H 'Name: value'` for repeatable custom headers - `--base-url <url>` to override the default COS API base URL for direct API calls - `--version` or `-v` to print the installed CLI version - `--help` or `-h` to print usage Subcommand notes: - `skills` does not accept `--json` - `skills` does not accept custom headers - `agent` does not accept `--json` - `agent` does not accept custom headers ## Supported paths ### Built-in catalog Use this to discover available skills: ```sh cosin --key <token> skills ``` Expected upstream skills include: - `/cos/crypto/chainlink/random` Returns a random value from the Chainlink-based skill endpoint. - `/cos/crypto/price/:symbol` Returns the latest price for a supported token symbol. Supported symbols for `/cos/crypto/price/:symbol`: - `BTC` - `ETH` - `HYPE` - `SOL` - `TRX` - `USDT` - `USDC` ### Direct COS API calls Use normal API paths to call COS directly: ```sh cosin --key <token> GET /v1/me cosin --key <token> POST /v1/orders --json '{"symbol":"BTCUSDT"}' ``` ### Skill calls through `/cos/...` Use `/cos/...` when you want to call a skill through COS: ```sh cosin --key <token> GET /cos/crypto/chainlink/random cosin --key <token> GET /cos/crypto/price/BTC ``` Internally, the CLI turns those into x402 pay-and-call requests to the COS backend. ## Use the agent shortcut Use `agent`, `agent status`, or `agent me` as a convenience alias for `GET /agent/me`. ```sh cosin --key <token> agent cosin --key <token> agent status cosin --key <token> agent me ``` Do not combine `agent` with `--json` or custom headers. ## Validate inputs before running - Ensure the path starts with `/` - Do not pass absolute URLs - Use `skills`, not `GET /skills` - Ensure `--json` is valid JSON - Ensure headers use `Name: value` - For `/cos/crypto/chainlink/random`, only use `GET` - For `/cos/crypto/price/:symbol`, only use `GET` and only the supported symbols ## Read the output Expect the CLI to: - Print an HTTP status line for normal API requests, `/cos/...` skill calls, and `agent` - Print only the upstream body for the `skills` subcommand - Pretty-print JSON response bodies - Print `<empty response body>` for empty responses - Return a non-zero exit code for unsuccessful HTTP responses or CLI argument errors ## Work locally in this repo Use the local build when working inside this repository: ```sh bun run build ./dist/index.js --key <token> agent ./dist/index.js --key <token> skills ./dist/index.js --key <token> GET /v1/me ./dist/index.js --key <token> GET /cos/crypto/chainlink/random ``` Use the published command shape locally when that is more convenient: ```sh bun x cosin --key <token> agent bun x cosin --key <token> skills bun x cosin --key <token> GET /v1/me bun x cosin --key <token> GET /cos/crypto/price/BTC ```