Getting started
Install
pip install gossetPython 3.9 or later. This installs the gosset command (and a gosset-cli alias), plus the gosset Python SDK.
gosset version # Gosset CLI v0.5.27
gosset --helpUpgrade for conference abstracts
gosset abstracts needs 0.5.27 or later. If gosset version shows an older release, upgrade:
pip install -U gossetAuthenticate
gosset authThis opens your browser once. The key is stored in ~/.config/gosset/credentials (readable only by you) and every later command picks it up, in this shell and in new ones. There is 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 auth --status # the key is shortened
Signed in: 1a2b3c…9f0e (from /home/you/.config/gosset/credentials)gosset login and gosset get-key are aliases for gosset auth.
No browser on this machine
On a server, in a container or over SSH, use the paste-the-code flow:
gosset auth --manual # prints a URL; open it on any machine
gosset auth --code <CODE> # paste the code that page shows yougosset auth usually notices there is no browser and switches to this by itself. Set GOSSET_FORCE_MANUAL_AUTH=1 to always use it.
Scripting and CI
In CI a stored file is thrown away with the container, so print the key instead:
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:
--api-keyon the commandGOSSET_API_KEYGOSSET_OAUTH_TOKEN- the key stored by
gosset auth
The environment beats the stored key, so GOSSET_API_KEY=... gosset drugs does what it looks like, and CI is not affected by whoever signed in last.
get-token is for MCP clients
gosset get-token signs you in and prints an OAuth token. MCP clients need that. The CLI, the SDK and the REST API use the API key from gosset auth instead; an OAuth token in GOSSET_API_KEY fails with "Authentication failed".
gosset get-token --quiet # only the token, for pasting into an MCP client configEnvironment variables
| Variable | Purpose | Default |
|---|---|---|
GOSSET_API_KEY | API key | the stored key |
GOSSET_OAUTH_TOKEN | Used when GOSSET_API_KEY is not set | |
GOSSET_API_URL | API base URL | https://api.gosset.ai |
GOSSET_CONFIG_DIR | Folder for the stored key | $XDG_CONFIG_HOME/gosset, else ~/.config/gosset |
GOSSET_FORCE_MANUAL_AUTH | 1: always use the paste-the-code sign-in |
The CLI talks to production (api.gosset.ai). To use another endpoint, set GOSSET_API_URL or pass --base-url.
Without a key you get a clear error and exit code 1:
$ gosset drugs --target PD-1
Error: no API key. Run `gosset auth` or set GOSSET_API_KEY (or pass --api-key).Running inside Claude Code, Codex or another sandbox?
Allow the host api.gosset.ai in the sandbox's network settings first. A blocked host looks like a sign-in problem but isn't. See Teach your agent.
Output formats
Every entity command prints JSON by default: an array with one object per result.
gosset drugs pembrolizumab --limit 1 --fields drug_id,name,phase[
{
"drug_id": "6753680d5ed849fb27bf3890",
"name": "pembrolizumab",
"phase": "Approved"
}
]Add --table for a readable view, and --fields to choose the fields:
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 # JSON with two fieldsA table shows the first 25 rows and the total:
… showing 25 of 761 totalField names come from gosset schema. Pipe JSON into jq:
gosset drugs --target TROP2 --phase Approved,3 | jq -r '.[].name'
gosset trials --disease obesity --phase 3 | jq '.[] | {nct: .nct_id, title: .title}'Flags every entity command takes
| Flag | Meaning |
|---|---|
--limit N | results per page (default 25; the server caps a page, see below) |
--offset N | rows to skip |
--all | fetch the whole set as one array (see below) |
--sort FIELD | sort on a field; prefix - for descending. Use the = form: --sort=-phase |
--fields a,b,c | return only these fields (JSON and table) |
--table / --json | table or JSON (JSON is the default) |
--include-ids | add id fields (target_ids, disease_class_ids, …) for joining records |
--where COND | any condition the named flags don't cover, see Query API |
--debug | print the query sent to the API, on stderr |
--api-key, --base-url | override the key or endpoint for one call |
A --sort field must be a published field name. An old name fails with a hint:
$ gosset drugs --target TL1A --sort=-latest_phase
{"error": "API error (400): unknown sort field 'latest_phase' for drugs. See GET /v3/schema/drugs."}--limit is a page size, not a total
Ask for more than a page holds and you get one page, with a warning on stderr:
$ gosset drugs --target PD-1 --limit 500 > out.json
warning: asked for 500 but the server returned 100 of 761; the page size is capped. Narrow the query with filters rather than a larger --limit.The warning only appears when more records exist. Asking for 500 and getting 12 because there are only 12 stays quiet.
To collect a whole set, use --all:
gosset drugs --target TL1A --all > tl1a.json # 75 drugs, one arrayIt pages for you, uses a stable sort, removes duplicates and prints progress on stderr, so the file stays clean. It refuses sets above 10,000 rows (exit code 2) and asks you to add filters. It can't be combined with --offset.
A bigger page is rarely what you want. Paging through a dataset is slow, counts against your plan's limits, and answers a broader question than the one you have:
# pages through the data # answers the question
gosset trials --limit 500 gosset trials --drug tulisokibart --phase 3Exit codes
| Code | Meaning |
|---|---|
0 | success, including an empty result |
1 | no key, an API error, or a malformed flag value (error as JSON on stderr) |
2 | a name you passed matched nothing; --all refused; or an invalid command line |
Errors are JSON on stderr and exit codes are meaningful, so the CLI is safe to script and to drive from an agent.
What the CLI sends
Every entity command sends one query object to POST /v3/{entity}/query. The server resolves your names to Gosset ids. --debug prints the object:
$ gosset drugs --target PD-1 --phase 3 --limit 3 --fields name --debug
POST drugs/query {"where": {"and": [{"field": "target", "value": "PD-1"}, {"field": "phase", "value": "3"}, {"field": "exclude_flags", "value": "is_combination"}]}, "sort": "-phase"}The exclude_flags condition is how gosset drugs hides trial-arm regimens by default; --include-combinations removes it. The Query API page covers the query object, --where, and how to see what each name matched.