# SDK and CLI

The official GrooveSheet npm package, @groovesheet/sdk, and its groovesheet command line tool: search the library, transcribe a file, poll the job, download the results.

`@groovesheet/sdk` is the official TypeScript client for the [REST API](/developers/docs/api), generated from the OpenAPI document, with a `groovesheet` command line tool in the same package. Node 20 or newer. Source and issues: [github.com/groovesheet/groovesheet-sdk](https://github.com/groovesheet/groovesheet-sdk).

```bash
npm i @groovesheet/sdk
# or, with no install
npx @groovesheet/sdk search "easy on me"
```

## CLI [#cli]

| Command | What it does |
| --- | --- |
| `groovesheet search <query> [--instrument drums] [--format sheet]` | Search the library |
| `groovesheet song <id-or-slug>` | Every part of one song and what it has |
| `groovesheet workflows` | The workflow names a transcription can use |
| `groovesheet transcribe <file> --instrument drums [--wait] [--out dir]` | Upload a file, start a job, optionally wait and download |
| `groovesheet job <id> [--wait]` | Poll a job |
| `groovesheet jobs` | Your recent jobs |
| `groovesheet download <id> [file_key] [--out dir]` | Download one output or all of them |
| `groovesheet account` | Plan and minutes left |
| `groovesheet login --email you@example.com` | Sign in: the CLI prints a code and a link, you approve on groovesheet.net |

Global flags: `--sandbox` (the [sandbox](/developers/docs/api#sandbox): no token, nothing charged), `--api-url`, `--token`, `--json`. Environment: `GROOVESHEET_TOKEN`, `GROOVESHEET_API_URL`, `GROOVESHEET_SANDBOX=1`.

```bash
# Try the whole loop without an account
groovesheet --sandbox transcribe any.mp3 --instrument drums --wait --out ./out
```

## SDK [#sdk]

```ts
import { GrooveSheet } from '@groovesheet/sdk';

const gs = new GrooveSheet({ token: process.env.GROOVESHEET_TOKEN });

const { tracks } = await gs.searchSongs({ query: 'easy on me' });
const song = await gs.getSong(tracks[0].id);

const job = await gs.transcribe({ file: 'song.mp3', instrument: 'drums' });
const done = await gs.waitForJob(job.workflow_id);
await gs.saveOutputs(done.workflow_id, './out');
```

`new GrooveSheet({ sandbox: true })` points every call at the sandbox. `GrooveSheet.login({ email, onCode })` runs the verified-email sign-in from [auth.md](/auth.md) and resolves to a token set.

In production, `transcribe` starts a paid job: it uses the account's minutes exactly as an upload on groovesheet.net does. The library and the sandbox are free.

## For an AI app rather than code [#for-an-ai-app-rather-than-code]

Use the [MCP server](/developers/docs) instead; the SDK is for programs. An agent that only needs to read about GrooveSheet can use the docs MCP server at `https://www.groovesheet.net/mcp/docs` or ask `POST https://www.groovesheet.net/ask` (NLWeb).
