Storage SDK

This page documents the earlier Code Storage SDKs: @pierre/storage, pierre-storage, and code-storage-go. New code uses the Pierre SDK. To move code to the new SDK, use the pierre-migrate skill.

Installation & Setup

pnpm i @pierre/storage

# Using uv (recommended)
uv add pierre-storage

# Or using pip
pip install pierre-storage

go get github.com/pierrecomputer/sdk/packages/code-storage-go@latest

Set PIERRE_ORG and PIERRE_PRIVATE_KEY as shown in the Quick Start. Pass them to the client:

import { GitStorage } from '@pierre/storage';

const store = new GitStorage({
  name: process.env.PIERRE_ORG!,
  key: process.env.PIERRE_PRIVATE_KEY!,
});

import os

from pierre_storage import GitStorage

storage = GitStorage({
    "name": os.environ["PIERRE_ORG"],
    "key": os.environ["PIERRE_PRIVATE_KEY"],
})

// Initialize the client
client, err := storage.NewClient(storage.Options{
  Name: os.Getenv("PIERRE_ORG"),
  Key:  os.Getenv("PIERRE_PRIVATE_KEY"),
})

Await store.createRepo() or store.findOne() to get a repo object. store.findOne() returns null if the repository does not exist. In Go, import os to read the environment variables. SDK calls take a context.Context, and TTL values are time.Duration (for example time.Hour).

Need to create a JWT without an SDK client? See Authentication → How to sign a JWT.

Token signing

The Python package exports generate_jwt for code that needs a token without a GitStorage client. The helper selects ES256 or RS256 from the key type.

Python

import os

from pierre_storage import generate_jwt

private_key = os.environ["PIERRE_PRIVATE_KEY"]
org = os.environ["PIERRE_ORG"]

token = generate_jwt(
    key_pem=private_key,  # Required. This key signs the JWT.
    issuer=org,  # Required. This parameter maps to iss.
    repo_id="team/project-alpha",  # Required. This parameter maps to repo.
    scopes=["git:read", "git:write"],  # Optional. This list maps to scopes and is the default.
    ttl=3600,  # Optional. This value sets exp from iat. The default is 31536000 seconds.
)

git_url = f"https://t:{token}@{org}.code.storage/team/project-alpha.git"
print(f"git clone {git_url}")

See Storage Access & Permissions for repository claims and scopes.

Error Handling

The SDK surfaces API failures as ApiError and ref update failures as RefUpdateError.

import { ApiError, RefUpdateError, GitStorage } from '@pierre/storage';

const store = new GitStorage({
  name: process.env.PIERRE_ORG!,
  key: process.env.PIERRE_PRIVATE_KEY!,
});

try {
  const repo = await store.createRepo({ id: 'existing' });
  console.log(repo.id);
} catch (err) {
  if (err instanceof ApiError) {
    console.error('API error:', err.message);
    console.error('Status code:', err.statusCode);
  } else {
    throw err;
  }
}

const repo = await store.findOne({ id: 'repo-id' });
const builder = repo?.createCommit({
  targetBranch: 'main',
  commitMessage: 'Update docs',
  author: { name: 'Docs Bot', email: 'docs@example.com' },
});

try {
  const result = await builder
    ?.addFileFromString('docs/changelog.md', '# v2.0.1\n- add streaming SDK\n')
    .send();
  console.log(result?.commitSha);
} catch (err) {
  if (err instanceof RefUpdateError) {
    console.error('Ref update failed:', err.message);
    console.error('Status:', err.status);
    console.error('Reason:', err.reason);
    console.error('Ref update:', err.refUpdate);
  } else {
    throw err;
  }
}

from pierre_storage import ApiError, RefUpdateError

try:
    repo = await storage.create_repo(id="existing")
except ApiError as e:
    print(f"API error: {e.message}")
    print(f"Status code: {e.status_code}")

try:
    result = await builder.send()
except RefUpdateError as e:
    print(f"Ref update failed: {e.message}")
    print(f"Status: {e.status}")
    print(f"Reason: {e.reason}")
    print(f"Ref update: {e.ref_update}")

// Initialize the client
client, err := storage.NewClient(storage.Options{
  Name: os.Getenv("PIERRE_ORG"),
  Key:  os.Getenv("PIERRE_PRIVATE_KEY"),
})

// Create a repository and handle API errors
_, err = client.CreateRepo(context.Background(), storage.CreateRepoOptions{ID: "existing"})
if err != nil {
  var apiErr *storage.APIError
  if errors.As(err, &apiErr) {
    fmt.Printf("API error: %s (status=%d)\n", apiErr.Message, apiErr.Status)
  } else {
    fmt.Printf("Unexpected error: %v\n", err)
  }
}

// Build a commit and handle ref update errors
repo, err := client.FindOne(context.Background(), storage.FindOneOptions{ID: "repo-id"})
builder, err := repo.CreateCommit(storage.CommitOptions{
  TargetBranch:  "main",
  CommitMessage: "Update docs",
  Author:        storage.CommitSignature{Name: "Docs Bot", Email: "docs@example.com"},
})

_, err = builder.AddFileFromString("docs/changelog.md", "# v2.0.1\n- add streaming SDK\n", nil).
  Send(context.Background())
if err != nil {
  var refErr *storage.RefUpdateError
  if errors.As(err, &refErr) {
    fmt.Printf("Ref update failed: %s (status=%s, reason=%s)\n", refErr.Message, refErr.Status, refErr.Reason)
  } else {
    fmt.Printf("Unexpected error: %v\n", err)
  }
}

Methods

Each method of the earlier SDK has its own page.

Getting Started

Platform

Workflows

Libraries

API Reference

Installation & Setup

Token signing

Error Handling

Methods

Client methods

Repository methods

​Installation & Setup

​Token signing

​Error Handling

​Methods

​Client methods

​Repository methods

Installation & Setup

Token signing

Error Handling

Methods

Client methods

Repository methods