TypeScript SDK
The Musher TypeScript SDK lets you pull bundles, resolve versions, verify integrity, and access typed assets from Node.js applications. Responses are validated with Zod schemas and all operations return typed handles.
Prerequisites
- Node.js 20 or later
- A Musher API key — create one in the Console
Installation
Install the package
npm install @musher-dev/musher-sdkSet your API key
export MUSHER_API_KEY="msk_..."Authentication
The SDK discovers credentials automatically, checking these sources in order:
MUSHER_API_KEYenvironment variable- OS keyring (
musher/<host>) - Credential file (
~/.local/share/musher/credentials/<host>/api-key) - Programmatic — pass a token directly
To pass a token programmatically:
import { MusherClient } from "@musher-dev/musher-sdk";
const client = new MusherClient({ apiKey: "msk_..." });Pull Your First Bundle
The pull() function downloads a bundle from the registry and returns a Bundle object with typed access to its contents.
import { pull } from "@musher-dev/musher-sdk";
const bundle = await pull("acme/code-review-kit");
console.log(bundle.manifest.name);
for (const asset of bundle.manifest.assets) {
console.log(`${asset.type}: ${asset.path}`);
}Work with Typed Handles
Bundles provide typed handles for each asset category. Each handle gives you structured access to the asset content and metadata.
import { pull } from "@musher-dev/musher-sdk";
const bundle = await pull("acme/code-review-kit");
// Access skills
for (const skill of bundle.skills) {
console.log(`Skill: ${skill.name}`);
console.log(skill.content);
}
// Access prompts
for (const prompt of bundle.prompts) {
console.log(`Prompt: ${prompt.name}`);
console.log(prompt.content);
}
// Access all files
for (const file of bundle.files) {
console.log(`${file.path} (${file.size} bytes)`);
}Resolve Without Pulling
Use resolve() to inspect a bundle's metadata without downloading its full contents. This
is useful for checking versions, listing assets, or validating a reference.
import { resolve } from "@musher-dev/musher-sdk";
const result = await resolve("acme/code-review-kit@^1.0");
console.log(`Resolved version: ${result.version}`);
console.log(`Asset count: ${result.assets.length}`);Configuration
Use configure() to customize the registry URL, cache directory, or other settings. Configuration
applies globally and affects all subsequent SDK calls.
import { configure } from "@musher-dev/musher-sdk";
configure({
registryUrl: "https://registry.musher.dev",
cacheDir: "/custom/cache",
});For more control, create a MusherClient instance directly:
import { MusherClient } from "@musher-dev/musher-sdk";
const client = new MusherClient({
apiKey: "msk_...",
registryUrl: "https://registry.musher.dev",
});
const bundle = await client.pull("acme/code-review-kit");Key Exports
| Export | Description |
|---|---|
pull() | Pull a bundle by reference |
resolve() | Resolve metadata without downloading |
configure() | Set global configuration (registry URL, cache, etc.) |
getClient() | Get or create the global client instance |
MusherClient | Client class for custom configuration |
Bundle | Loaded bundle with typed asset access |
BundleRef | Parsed bundle reference (publisher/name@version) |
Selection | Filter and select specific assets from a bundle |
SkillHandle | Typed handle for skill assets |
PromptHandle | Typed handle for prompt assets |
ToolsetHandle | Typed handle for toolset assets |
AgentSpecHandle | Typed handle for agent spec assets |
FileHandle | Typed handle for generic file assets |