Installing trace-edu-sdk installs a trace command.
trace --help
trace --version
Global options#
These come before the subcommand.
| Option | Meaning |
|---|---|
--base-url URL | The Trace to talk to. Overrides TRACE_BASE_URL. |
--api-key KEY | Use this key instead of the stored one. Overrides TRACE_API_KEY. |
--version | Print the package version and exit. |
trace --base-url http://localhost:8000 credits
trace login#
Get a key by approving in the browser, and store it on this machine.
trace login
trace login --name "Laptop"
trace login --no-browser
| Option | Default | Meaning |
|---|---|---|
--name NAME | CLI | A name for the key, shown at /account/developer. |
--no-browser | off | Print the link instead of opening a browser. Use over SSH. |
Output:
Your login code: Q4EB-FUD7
Approve it at: https://trace.edu/account/link?code=Q4EB-FUD7
Waiting for you to approve… (Ctrl-C to cancel)
Signed in. Key saved to /Users/you/.trace/credentials.json (readable only by you).
Try it: trace credits
Check that the code in the browser matches the one in your terminal before approving. Codes expire after 10 minutes and work once. Full description of the flow: Authentication.
trace logout#
Delete the key stored on this machine.
trace logout
This removes ~/.trace/credentials.json. It does not revoke the key on your
account — if the key may have been seen by someone else, revoke it at
/account/developer.
trace whoami#
Show which key and which Trace this machine is using, and the balance.
trace whoami
Trace: https://trace.edu/api/sdk/v1
Key: trace_sk_5PRWvg7w…
Name: Laptop
Balance: 472.5 credits
Only the prefix is printed, never the full key, so this is safe to run while screen-sharing.
Exits 1 with Not signed in. Run trace login. when there is no key.
trace credits#
Show the balance, and optionally the recent ledger.
trace credits
trace credits --usage # last 10 entries
trace credits --usage 25 # last 25
Balance: 472.5 credits
When Kind Model Credits
2026-08-06 10:14:02 settlement deepseek/deepseek-v4-flash-0731 0.0504
2026-08-06 10:14:02 spend deepseek/deepseek-v4-flash-0731 -0.0523
2026-08-06 10:02:11 grant — 500.0000
A request writes two rows: the reservation, then its provider-cost settlement.
Why two rows per request: Credits and limits.
trace models#
List the models this account can call and what each costs.
trace models
Model Type Tools Credits / 1K tokens
deepseek/deepseek-v4-flash-0731:nitro chat yes 0.1500
openai/gpt-5.6-luna chat yes 0.2000
openai/text-embedding-3-small embedding no 0.0200
1 credit = $0.001 of upstream cost. Rates estimate the reservation.
Every model listed is on Trace's reviewed child-safe roster; nothing else is callable. See Authentication.
Environment variables#
| Variable | Meaning |
|---|---|
TRACE_API_KEY | Use this key. Takes priority over the stored file. |
TRACE_BASE_URL | Which Trace to talk to. Accepts the origin or the full gateway URL. |
TRACE_CONFIG_DIR | Move ~/.trace somewhere else. |
Exit codes#
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | A Trace error, or no subcommand given. The reason is on stderr. |
| 130 | Cancelled with Ctrl-C. |
Errors print one message to stderr, never a traceback:
$ trace credits
Not enough credits: your balance is 0 and this request needs about 0.05.
Check your balance with `trace credits`, or ask your teacher for a grant.