CLI EN

CLI

English | 简体中文

---

The repository ships a command-line client, typesafe, built on the standard library only. It wraps the same Client the library exposes: same configuration, same retries, same typed errors, and full multimodal capabilities.

---

Install

# Latest release into $(go env GOPATH)/bin
go install github.com/guchengod/typesafe-sdk-go/cmd/typesafe@latest

Or download a prebuilt binary for your platform from Releases — darwin, linux, and windows, on amd64 and arm64.

export TYPESAFE_API_KEY="ts_live_..."
typesafe version

---

Commands

Command	Purpose
typesafe ask	Ask named questions about a state (System One)
typesafe models	List the models available to the account
typesafe version	Print the CLI and runtime version
typesafe help	Print the command reference

---

Connection Flags

Accepted by every command, before or after the command name. A flag given to the command wins over the same flag given before it.

Flag	Meaning
--api-key string	API key (default $TYPESAFE_API_KEY)
--base-url string	API root (default $TYPESAFE_BASE_URL)
--timeout duration	Timeout for one attempt (default 10s)
--retries int	Retries after the first attempt (default 2)
--verbose	Log requests and responses to stderr

typesafe --api-key "$KEY" models
typesafe models --api-key "$KEY"     # equivalent

---

ask

typesafe ask --state <state> [--model <name>] [<questions>] [--format json|text] [--images] [--long-context]

1. Providing State (--state)

--state is what the questions refer to. It accepts:

Form	Example
Inline JSON	--state '{"body": "I was charged twice."}'
A plain string	--state "I was charged twice."
A file	--state @ticket.json
Standard input	--state -

2. Specifying Questions

# Convenience flags, each repeatable
--noul   'billing=Is this about billing?'
--choice 'queue=billing:Charges/refunds,technical:API issues,other'
--score  'urgency=routine,elevated,critical'
--box    'target=Locate the main object in the image'

# Or a JSON object of named questions, inline, from a file, or from stdin
--questions '{"billing": {"type": "noul", "instructions": "Is this about billing?"}}'
--questions @questions.json
--questions -

• --choice labels are label or label:description; a label without a description is sent as null.
• --box defines an object localization question.
• A name may be defined only once across --questions and convenience flags.

3. Danger Zone Flags

Flag	Description
--images	Sets x-typesafe-images: true, enabling image and box questions
--long-context	Sets x-typesafe-long-context: true, enabling 262k token context window

4. Examples

Reading a ticket from stdin and piping into jq:

cat ticket.txt | typesafe ask --state - --noul 'spam=Is this spam?' | jq '.answers.spam.noul'

Asking several questions at once with text summary output:

typesafe ask \
  --state @ticket.json \
  --model jev-preview \
  --images \
  --noul 'billing=Is this about billing?' \
  --choice 'queue=billing:Charges,technical:API issues,other' \
  --score 'urgency=routine,elevated,critical' \
  --box 'badge=the VIP badge in the screenshot' \
  --format text

Text output:

model    jev-1.13.0
usage    Usage{input_tokens: 367, output_tokens: 69}
billing  noul 0.9900
queue    choice billing (confidence 1.00)
urgency  score 0.53 of 2 (confidence 0.20)
badge    box [0.12, 0.45, 0.38, 0.82] (confidence 0.95)

---

models

typesafe models                # JSON
typesafe models --format text  # a table

NAME         RELEASE                           DESCRIPTION
jev-latest   2026-09-10T18:38:01.391457+00:00  The latest iteration of TypeSafe's System One Model: Jev
jev-preview  2026-09-15T10:00:00.000000+00:00  Experimental multimodal and bounding box localization model

---

Output Formats

--format json (the default) prints the API response indented, ready to pipe into jq. --format text prints a readable summary: the model, token usage, and one line per answer.

---

Exit Codes

Code	Meaning
0	Success
1	Usage or input error; nothing was sent
2	The API returned an unsuccessful status (4xx or 5xx)
3	The request never reached the API

if ! typesafe ask --state @ticket.json --noul 'spam=Is this spam?' > answer.json; then
  case $? in
    2) echo "the API rejected the request" >&2 ;;
    3) echo "could not reach the API" >&2 ;;
    *) echo "bad invocation" >&2 ;;
  esac
  exit 1
fi

---

Diagnostics

--verbose logs wire traffic to stderr through log/slog, with credential headers redacted:

typesafe ask --state @ticket.json --noul 'q=Is this spam?' --verbose > answer.json