npm SDK

The ticket-rs npm package provides native TypeScript bindings to ticket-rs, giving you full access to issue management and graph analytics from Node.js and Bun. Every visible tk subcommand has a typed TypeScript wrapper, generated from the same clap::Command tree the binary parses against — so the TypeScript surface stays in lockstep with the CLI by construction. Calls go through an in-process napi FFI; no subprocess is spawned.

Installation

bun (Recommended)
npm
Globally (CLI only)

bun add ticket-rs

This project standardises on bun for TypeScript work; if you maintain a Node.js project, npm and yarn install the same artefact.

npm install ticket-rs

npm install -g ticket-rs

Installs the tk CLI binary globally. The TypeScript bindings still require a per-project install.

The postinstall step downloads (or builds) the prebuilt native module for your platform. No Rust toolchain required for the supported triples below; if your platform isn’t listed, install Rust and the package will compile from source.

Quick Start

import * as tk from "ticket-rs";

// Every visible `tk` subcommand is a top-level function.
// Pass an options object the same way you'd pass flags on the CLI.

// Initialise a tickets directory
tk.init({ dir: "/path/to/your/project" });

// Get issues ready to work on (no open blockers)
const ready = tk.ready({
  dir: "/path/to/your/project",
  format: "json",
}) as Array<{ id: string; title: string }>;

for (const issue of ready) {
  console.log(`${issue.id}: ${issue.title}`);
}

// Get repository statistics
const stats = tk.stats({
  dir: "/path/to/your/project",
  format: "json",
}) as { open: number; closed: number; ready: number };

console.log(`Open: ${stats.open}  Closed: ${stats.closed}  Ready: ${stats.ready}`);

API Reference

ticket-rs exposes three categories of API:

76 typed wrappers — one per visible tk subcommand. Type signatures come from clap.
napiDispatch(argv) — raw escape hatch for any command, including hidden ones.
commandSpec() — introspect the CLI surface as a nested JSON spec.

Typed wrappers

Each wrapper takes the command’s flags as properties of a single options object. The munging rules:

kebab-case becomes camelCase: --dry-run → dryRun
nested commands are namespaced: tk dep add → depAdd
the JS reserved word delete gets a trailing underscore: tk delete → delete_
global flags dir, format, json, and strict are accepted on every wrapper

Return value depends on format:

format: "json" → parsed JSON (unknown; narrow at the call site)
omitted or any other value → the raw stdout string

import * as tk from "ticket-rs";

// Core issue management
tk.create({ title: "Fix the bug", priority: 1, format: "json" });
const issue = tk.show({ id: "tk-abc123", format: "json" });
tk.update({ id: "tk-abc123", status: "in_progress" });
tk.close({ id: "tk-abc123", reason: "fixed" });
const issues = tk.list({ format: "json" });

// Dependencies (nested commands become camelCase)
tk.depAdd({ blocked: "tk-1", blocker: "tk-2" });
tk.depTree({ id: "tk-1" });

// AI/analytics
const triage = tk.triage({ format: "json" });
const priority = tk.priority({ format: "json" });
const plan = tk.plan({ format: "json" });
const nextPick = tk.next({ format: "json" });

// Reserved word `delete` becomes `delete_`
tk.delete_({ id: "tk-abc123" });

// kebab-case flags become camelCase
tk.depAdd({ blocked: "tk-1", blocker: "tk-2", dryRun: true });

The full surface includes every visible tk command — linearSync, githubSync, claudeSync, worktree, stacks, insights, search, similar, validate, lint, and more. Discover them at runtime:

import { TYPED_API_FUNCTIONS } from "ticket-rs";
console.log([...TYPED_API_FUNCTIONS].sort());

`napiDispatch(argv)`

Raw escape hatch for any command, including hidden ones. Same in-process napi path; you build the argv array yourself.

import { napiDispatch } from "ticket-rs";

// Equivalent to `tk list --format json -C /path/to/repo`
const out = napiDispatch(["list", "--format", "json", "-C", "/path/to/repo"]);

// Returns the raw stdout string. Parse it yourself.
const issues = JSON.parse(out);

`commandSpec()`

Introspect the CLI surface as a nested JSON spec — useful for building meta-tools, generating other typed bindings, or discovering commands and their flags programmatically.

import { commandSpec } from "ticket-rs";

const spec = JSON.parse(commandSpec());
// spec = { name: "tk", subcommands: [...], global_args: [...] }

// List every visible top-level command
for (const cmd of spec.subcommands) {
  if (!cmd.hidden) {
    console.log(cmd.name, "—", cmd.about ?? "");
  }
}

Error handling

All errors surface as plain Error instances — not TypeError. The split between argv-parse failures and runtime failures is carried on err.code:

`err.code`	Cause
`"InvalidArg"`	argv didn’t parse (unknown subcommand, bad flag, missing required positional). Fix the call.
`"GenericFailure"`	argv parsed fine but the command itself failed (issue not found, parse error in a ticket file, etc.). The system refused.

napi-derive wraps every Err(_) from Rust in a plain JsError (which presents as Error in JS), not a TypeError. Don’t write catch (err) { if (err instanceof TypeError) ... } — that branch will never fire. Use err.code to discriminate.

import * as tk from "ticket-rs";

try {
  tk.show({ id: "tk-doesnotexist" });
} catch (err) {
  // All errors are plain Error instances. Discriminate via .code:
  const code = (err as { code?: string }).code;
  if (code === "GenericFailure") {
    // The command ran but failed — issue doesn't exist
    console.error(`command failed: ${(err as Error).message}`);
  } else if (code === "InvalidArg") {
    // You mis-typed the call — bad flag, missing arg, etc.
    console.error(`bad call: ${(err as Error).message}`);
  } else {
    throw err;
  }
}

Return shapes

When you pass format: "json", wrappers return parsed JSON. The shape mirrors what tk <command> --format json emits on the CLI. The TypeScript type is unknown — narrow with a type guard or zod in your code. (The clap surface doesn’t carry per-command output schemas; pinning them in TS would be a separate source of truth that could drift.)

// list({ format: "json" }) → array of issues
[
  { id: "tk-abc", title: "Fix bug", status: "open", priority: 1 },
]

// triage({ format: "json" }) → dict with nested structure
{
  quick_ref: { total: 42, open: 18, ready: 5 },
  recommendations: [{ id: "tk-abc", score: 87.5, reason: "..." }],
  quick_wins: [],
  blockers_to_clear: [],
}

// stats({ format: "json" }) → flat counts
{ total: 42, open: 18, in_progress: 3, blocked: 2, closed: 19, ready: 5 }

For the exact shape of each command’s JSON, run tk <command> --format json once and inspect.

Migration from the hand-written client

The previous createClient / Client API has been removed — src/client.ts, src/models.ts, and src/batch.ts are gone. Replace client.method(...) calls with the corresponding typed wrapper:

Before	After
`createClient().listIssues()`	`tk.list({ format: "json" })`
`client.readyIssues()`	`tk.ready({ format: "json" })`
`client.computePriorities()`	`tk.priority({ format: "json" })`
`client.computeTriage()`	`tk.triage({ format: "json" })`
`client.generatePlan()`	`tk.plan({ format: "json" })`
`client.getVersion()`	`tk.version({})`
Anything else	`napiDispatch(["<cmd>", ...args])`

The migration is mechanical — every old client method maps either to a typed wrapper named after its tk subcommand, or to a raw napiDispatch call.

Examples

Find high-priority ready issues

import * as tk from "ticket-rs";

const ready = tk.ready({ format: "json" }) as Array<{
  id: string;
  title: string;
  priority: number;
}>;

const highPriority = ready.filter((i) => i.priority <= 1);
for (const issue of highPriority) {
  console.log(`[P${issue.priority}] ${issue.id}: ${issue.title}`);
}

Batch create issues

import * as tk from "ticket-rs";

const tasks: Array<[string, string, number]> = [
  ["Set up CI/CD", "task", 1],
  ["Write documentation", "task", 2],
  ["Add unit tests", "task", 2],
];

for (const [title, issueType, priority] of tasks) {
  const out = tk.create({
    title,
    issueType,
    priority,
    format: "json",
  }) as { id: string };
  console.log(`Created: ${out.id}`);
}

Export issues to JSON

import { writeFileSync } from "node:fs";
import * as tk from "ticket-rs";

const issues = tk.list({ format: "json" }) as Array<{
  id: string;
  title: string;
  status: string;
  priority: number;
}>;

const data = issues.map((i) => ({
  id: i.id,
  title: i.title,
  status: i.status,
  priority: i.priority,
}));

writeFileSync("issues.json", JSON.stringify(data, null, 2));

Run a hidden command via the escape hatch

import { napiDispatch } from "ticket-rs";

// Hidden commands aren't surfaced as typed wrappers, but `napiDispatch`
// reaches them by argv. Useful for the MCP server and internal tools.
const out = napiDispatch(["migrate-beads", "--dry-run"]);
console.log(out);

Platform Support

Pre-built native modules are shipped for:

Platform	Architectures	Node.js Versions
Linux	x86_64, aarch64	18+
macOS	x86_64 (Intel), arm64 (Apple Silicon)	18+
Windows	x86_64	18+

If no pre-built module exists for your platform, the postinstall step compiles from source (requires Rust toolchain).

Troubleshooting

Error: Cannot find module '../native/ticket_rs_bindings.node'

The native bindings weren’t installed. If you cloned the repo, run:

cd npm && bun run build

If you installed from npm and the postinstall step failed, reinstall with verbose logging:

bun install --verbose ticket-rs

ImportError: cannot import name 'createClient' / 'TicketRsClient' / ...

The hand-written createClient / Client API was removed when the typed_api surface shipped. The src/client.ts, src/models.ts, and src/batch.ts files are gone.

// Before (removed)
import { createClient } from "ticket-rs";
const client = createClient();
client.listIssues();

// After
import * as tk from "ticket-rs";
tk.list({ format: "json" });

See the Migration table above, or use napiDispatch(["list", "-f", "json"]) as the raw escape hatch.

catch (err) { if (err instanceof TypeError) ... } never fires

By design. napi-derive wraps every Rust Err(_) in a plain JsError that presents as Error (not TypeError) in JS. Discriminate via err.code:

catch (err) {
  const code = (err as { code?: string }).code;
  if (code === "InvalidArg") {
    // argv parse failure
  } else if (code === "GenericFailure") {
    // runtime failure (e.g. issue not found)
  }
}

See Error handling for the full table.

Build fails during npm install

The package contains a native Node addon. If no pre-built native module exists for your platform, you need:

Rust toolchain: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Node.js 18+ with headers

Then re-run install:

bun install ticket-rs

Getting Started

Concepts

CLI Reference

Integrations

About

Blog

Installation

Quick Start

API Reference

Typed wrappers

`napiDispatch(argv)`

`commandSpec()`

Error handling

Return shapes

Migration from the hand-written client

Examples

Find high-priority ready issues

Batch create issues

Export issues to JSON

Run a hidden command via the escape hatch

Platform Support

Troubleshooting

Next Steps

MCP Server

CLI Reference

​Installation

​Quick Start

​API Reference

​Typed wrappers

​napiDispatch(argv)

​commandSpec()

​Error handling

​Return shapes

​Migration from the hand-written client

​Examples

​Find high-priority ready issues

​Batch create issues

​Export issues to JSON

​Run a hidden command via the escape hatch

​Platform Support

​Troubleshooting

​Next Steps

MCP Server

CLI Reference

Installation

Quick Start

API Reference

Typed wrappers

`napiDispatch(argv)`

`commandSpec()`

Error handling

Return shapes

Migration from the hand-written client

Examples

Find high-priority ready issues

Batch create issues

Export issues to JSON

Run a hidden command via the escape hatch

Platform Support

Troubleshooting

Next Steps