Getting started

Install

pip install gosset

This installs the gosset command (and a gosset-cli alias), plus the importable gosset SDK.

gosset version
gosset --help

Authenticate

The CLI authenticates with a Bearer token. Get one interactively:

gosset get-token

This registers an OAuth client, opens your browser to authorize, and prints an access token. Export it (or pass --api-key per call):

export GOSSET_API_KEY="<your-token>"
gosset drugs --target PD-1 --limit 5

get-token --quiet prints only the token, so you can capture it directly:

export GOSSET_API_KEY=$(gosset get-token --quiet)

Environment variables

Variable	Purpose	Default
GOSSET_API_KEY	Bearer token (also GOSSET_OAUTH_TOKEN)	(required)
GOSSET_API_URL	API base URL	https://api.gosset.ai

The CLI targets production (api.gosset.ai) by default. To point at another environment, set GOSSET_API_URL or pass --base-url.

If no token is found you get a clear error and a non-zero exit code:

$ gosset drugs --target PD-1
Error: no API key. Run `gosset get-token` or set GOSSET_API_KEY (or pass --api-key).

Output formats

Every entity command prints JSON by default: the full object per result:

gosset drugs "pembrolizumab" --limit 1
# [ { "name": "pembrolizumab", "latest_phase": "Approved", "developers": [...], ... } ]

Add --table for a compact human view, or --fields to project specific keys:

gosset drugs --target PD-1 --phase 3 --table
gosset drugs --target PD-1 --fields name,latest_phase,developers --table
gosset drugs --target PD-1 --fields name,latest_phase           # projected JSON

Pipe JSON into jq (the default output is a JSON array):

gosset drugs --target TROP2 --phase Approved,3 | jq -r '.[].name'
gosset trials "obesity" --phase 3 | jq '.[] | {nct: .nct_id, name: .brief_study_name}'

Global flags

Available on every entity command (drugs / trials / companies / deals / news):

Flag	Meaning
--limit N	max results (default 25)
--offset N	pagination offset
--sort FIELD	sort field; prefix - for descending; use the = form so the shell/argparse accepts the leading dash: --sort=-latest_phase
--fields a,b,c	project to these fields (JSON and table)
--table	render a table instead of JSON
--json	force JSON (the default)
--debug	print the resolved request payload to stderr
--api-key, --base-url	override auth / endpoint per call

Exit codes

Code	Meaning
0	success
1	auth failure or an API error (error printed as JSON on stderr)
2	a name/filter you passed could not be resolved (empty result)

Because errors are JSON on stderr and exit codes are meaningful, the CLI is safe to script and to drive from an agent.

Debugging resolution

Every command sends a structured query object to POST /v2/{entity}/query; the server resolves your names to Gosset ids. --debug prints the exact query object that was sent:

$ gosset drugs --target PD-1 --phase 3 --limit 3 --debug
POST /v2/drugs/query  {"where": {"and": [{"field": "target", "value": "PD-1"}, {"field": "phase", "value": "3"}]}, "sort": "-latest_phase"}

The names are resolved server-side, so what each name became (matched entity, id count, runner-up candidates) comes back in the response's resolved block, not from --debug. See Query API for the query object and the resolved echo.