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

gosset auth

That opens your browser once. The key is stored in ~/.config/gosset/credentials (mode 0600) and every later command picks it up, in this shell and in new ones. There's nothing to export and nothing to add to a shell profile.

gosset auth --status     # signed in? which key? from where?
gosset auth --logout     # remove the stored key

gosset login and gosset get-key are aliases for the same command.

Not get-token

gosset get-token returns a raw OAuth token. MCP clients need that; this API doesn't accept it: the REST endpoints validate bearers against your account's API key, so an OAuth token fails every call with "Authentication failed". Use gosset auth.

Scripting and CI

A file in a container that gets thrown away is no use, so for CI print the export line instead of storing it:

eval "$(gosset auth --print-export)"
# or capture just the value
export GOSSET_API_KEY="$(gosset auth --quiet)"

Where the key comes from

Highest precedence first:

1. --api-key on the command
2. GOSSET_API_KEY
3. GOSSET_OAUTH_TOKEN
4. the key stored by gosset auth

Environment beats the stored key, so GOSSET_API_KEY=... gosset drugs does what it looks like it does and CI is unaffected by whoever last signed in.

Environment variables

Variable	Purpose	Default
GOSSET_API_KEY	Bearer token (also GOSSET_OAUTH_TOKEN)	(uses the stored key)
GOSSET_API_URL	API base URL	https://api.gosset.ai
GOSSET_CONFIG_DIR	Where the stored key lives	~/.config/gosset

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

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

$ gosset drugs --target PD-1
Error: no API key. Run `gosset auth` 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", "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,phase,developers --table
gosset drugs --target PD-1 --fields name,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; the server caps a page at 100, see below)
--offset N	pagination offset
--sort FIELD	sort field; prefix - for descending; use the = form so the shell/argparse accepts the leading dash: --sort=-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

--limit is a page size, not a total

Responses are paged. Ask for more than a page holds and you get one page, with a note on stderr rather than a short result that looks complete:

$ gosset drugs --limit 500 > out.json
warning: asked for 500 but the server returned 100 of 88,545; the page size is
capped. Narrow the query with filters rather than a larger --limit.

The warning only fires when more records exist, so asking for 500 and getting 12 because there are only 12 stays quiet.

To collect a whole cohort, use --all and let the CLI do it:

gosset drugs --target TROP2 --all > drugs.json

It pages internally, picks a stable sort, deduplicates and emits one array. It refuses above 10,000 rows and asks you to add filters. --offset is still there if you want a specific page.

A bigger --limit is rarely the answer anyway. Paging the corpus is slow, counts against your coverage limit, and usually answers a broader question than the one you have:

# pages the corpus                  # answers the question
gosset trials --limit 500           gosset trials --drug tulisokibart --phase 3

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": "-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.