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