Skip to content

Getting started ​

Install ​

bash
pip install gosset

Python 3.9 or later. This installs the gosset command (and a gosset-cli alias), plus the gosset Python SDK.

bash
gosset version          # Gosset CLI v0.5.27
gosset --help

Upgrade for conference abstracts

gosset abstracts needs 0.5.27 or later. If gosset version shows an older release, upgrade:

bash
pip install -U gosset

Authenticate ​

bash
gosset auth

This 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.

bash
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:

bash
gosset auth --manual        # prints a URL; open it on any machine
gosset auth --code <CODE>   # paste the code that page shows you

gosset 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:

bash
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

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

bash
gosset get-token --quiet    # only the token, for pasting into an MCP client config

Environment variables ​

VariablePurposeDefault
GOSSET_API_KEYAPI keythe stored key
GOSSET_OAUTH_TOKENUsed when GOSSET_API_KEY is not set
GOSSET_API_URLAPI base URLhttps://api.gosset.ai
GOSSET_CONFIG_DIRFolder for the stored key$XDG_CONFIG_HOME/gosset, else ~/.config/gosset
GOSSET_FORCE_MANUAL_AUTH1: 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.

bash
gosset drugs pembrolizumab --limit 1 --fields drug_id,name,phase
json
[
  {
    "drug_id": "6753680d5ed849fb27bf3890",
    "name": "pembrolizumab",
    "phase": "Approved"
  }
]

Add --table for a readable view, and --fields to choose the fields:

bash
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 fields

A table shows the first 25 rows and the total:

… showing 25 of 761 total

Field names come from gosset schema. Pipe JSON into jq:

bash
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 ​

FlagMeaning
--limit Nresults per page (default 25; the server caps a page, see below)
--offset Nrows to skip
--allfetch the whole set as one array (see below)
--sort FIELDsort on a field; prefix - for descending. Use the = form: --sort=-phase
--fields a,b,creturn only these fields (JSON and table)
--table / --jsontable or JSON (JSON is the default)
--include-idsadd id fields (target_ids, disease_class_ids, …) for joining records
--where CONDany condition the named flags don't cover, see Query API
--debugprint the query sent to the API, on stderr
--api-key, --base-urloverride 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:

bash
gosset drugs --target TL1A --all > tl1a.json      # 75 drugs, one array

It 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:

bash
# pages through the data              # answers the question
gosset trials --limit 500             gosset trials --drug tulisokibart --phase 3

Exit codes ​

CodeMeaning
0success, including an empty result
1no key, an API error, or a malformed flag value (error as JSON on stderr)
2a 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.

Gosset Documentation