Getting Started

Install the SDK and read a file from a repo in under 2 minutes.

Quickstart

npm install @githosted/sdk

import { Client } from "@githosted/sdk";

const client = new Client({ token: "gw_your_workspace_token" });
const repo = client.repo("my-project");

const files = await repo.ls("src/");
console.log(files);
// [{ name: "main.ts", type: "file" }, { name: "lib", type: "directory" }]

const file = await repo.read("src/main.ts");
console.log(file.content);
// "console.log('hello');"

Installation

# npm
npm install @githosted/sdk

# pnpm
pnpm add @githosted/sdk

# yarn
yarn add @githosted/sdk

Authentication

The SDK needs a workspace token (gw_) or repo token (gr_). Pass it directly or set the GITHOSTED_TOKEN environment variable:

export GITHOSTED_TOKEN=gw_your_workspace_token

// Explicit token
const client = new Client({ token: "gw_xxx" });

// Auto-reads GITHOSTED_TOKEN from env (Node.js only)
const client = new Client();

See Authentication for the full credential resolution order.

Reading and Writing

const repo = client.repo("my-project");

// Read a file
const file = await repo.read("README.md");
console.log(file.content);    // file contents as string
console.log(file.headSha);    // branch tip SHA — use for optimistic concurrency

// Write a file
await repo.write("README.md", "# Updated readme", {
  message: "Update readme",
});

// Atomic multi-file commit
await repo.transaction("Add feature", async (tx) => {
  await tx.write("src/feature.ts", featureCode);
  await tx.write("src/feature.test.ts", testCode);
});

Using Repo IDs

Repos have stable IDs (rp_ prefix) that don’t change on rename. You can reference repos by slug or ID: