Quick Start

Use the Code Storage SDK to create your first repository. Choose the TypeScript, Python, or Go example in each step. Later steps reuse the storage and repo values from the earlier steps. First create an API key and store it. See Authentication & Security. You need your organization identifier and the PIERRE_PRIVATE_KEY value from that step.

1. Install the SDK

pnpm add @pierre/storage

pip install pierre-storage

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

2. Initialize the client

Replace your-org with your organization identifier. The client reads the private key from PIERRE_PRIVATE_KEY.

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

const storage = new GitStorage({
  name: 'your-org',
  key: process.env.PIERRE_PRIVATE_KEY!,
});

import os

from pierre_storage import GitStorage

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

client, err := storage.NewClient(storage.Options{
	Name: "your-org",
	Key:  os.Getenv("PIERRE_PRIVATE_KEY"),
})
if err != nil {
	return fmt.Errorf("create client: %w", err)
}

3. Create a repository

Each repository belongs to your organization and has a unique ID. Code Storage can generate a UUID, or you can supply an ID such as team/project-alpha. A new repository uses main as its default branch.

// Create a repository with a server-generated ID.
const generatedRepo = await storage.createRepo();
console.log(generatedRepo.id); // e.g. '123e4567-e89b-12d3-a456-426614174000'

// Or create a repository with your own ID.
const repo = await storage.createRepo({ id: 'quickstart' });

// Or create a repository that syncs with GitHub.
const syncedRepo = await storage.createRepo({
  id: 'hello-world',
  baseRepo: { owner: 'octocat', name: 'Hello-World', defaultBranch: 'main' },
});

// Get an authenticated Git remote URL.
const url = await repo.getRemoteURL();
console.log(`git remote add origin ${url}`);
// Output: git remote add origin https://t:JWT@[org].code.storage/quickstart.git

# Create a repository with a server-generated ID.
generated_repo = await storage.create_repo()
print(generated_repo.id)  # e.g. '123e4567-e89b-12d3-a456-426614174000'

# Or create a repository with your own ID.
repo = await storage.create_repo(id="quickstart")

# Or create a repository that syncs with GitHub.
synced_repo = await storage.create_repo(
    id="hello-world",
    base_repo={"owner": "octocat", "name": "Hello-World", "default_branch": "main"},
)

# Get an authenticated Git remote URL.
url = await repo.get_remote_url()
print(f"git remote add origin {url}")

ctx := context.Background()

// Create a repository with a server-generated ID.
generatedRepo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{})
if err != nil {
	return fmt.Errorf("create repository: %w", err)
}
fmt.Println(generatedRepo.ID) // e.g. "123e4567-e89b-12d3-a456-426614174000"

// Or create a repository with your own ID.
repo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{ID: "quickstart"})
if err != nil {
	return fmt.Errorf("create repository: %w", err)
}

// Or create a repository that syncs with GitHub.
syncedRepo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
	ID:       "hello-world",
	BaseRepo: storage.GitHubBaseRepo{Owner: "octocat", Name: "Hello-World", DefaultBranch: "main"},
})
if err != nil {
	return fmt.Errorf("create synced repository: %w", err)
}

// Get an authenticated Git remote URL.
url, err := repo.RemoteURL(ctx, storage.RemoteURLOptions{})
if err != nil {
	return fmt.Errorf("create remote URL: %w", err)
}
fmt.Printf("git remote add origin %s\n", url)

To sync with GitLab, Bitbucket, or another HTTPS host, pass a base repository. See GitHub Sync and Generic Sync.

4. Create a commit

Write files and commit them to repo without a local clone.

const result = await repo
  .createCommit({
    targetBranch: 'main',
    commitMessage: 'Initial commit',
    author: { name: 'Your Name', email: 'you@example.com' },
  })
  .addFileFromString('README.md', '# Quickstart\n')
  .send();

console.log(result.commitSha);

result = await (
    repo.create_commit(
        target_branch="main",
        commit_message="Initial commit",
        author={"name": "Your Name", "email": "you@example.com"},
    )
    .add_file_from_string("README.md", "# Quickstart\n")
    .send()
)

print(result["commit_sha"])

builder, err := repo.CreateCommit(storage.CommitOptions{
	TargetBranch:  "main",
	CommitMessage: "Initial commit",
	Author:        storage.CommitSignature{Name: "Your Name", Email: "you@example.com"},
})
if err != nil {
	return fmt.Errorf("create commit builder: %w", err)
}

result, err := builder.
	AddFileFromString("README.md", "# Quickstart\n", nil).
	Send(ctx)
if err != nil {
	return fmt.Errorf("create commit: %w", err)
}

fmt.Println(result.CommitSHA)

5. Read repository data

Read files, list commits, and stream file content from repo.

// List files.
const files = await repo.listFiles();
console.log(files.paths);

// List recent commits.
const commits = await repo.listCommits({ limit: 10 });
for (const commit of commits.commits) {
  console.log(`${commit.sha.slice(0, 7)} ${commit.message}`);
}

// Read file content.
const response = await repo.getFileStream({ path: 'README.md' });
console.log(await response.text());

# List files.
files = await repo.list_files()
print(files["paths"])

# List recent commits.
commits = await repo.list_commits({"limit": 10})
for commit in commits["commits"]:
    print(f"{commit['sha'][:7]} {commit['message']}")

# Read file content.
response = await repo.get_file_stream({"path": "README.md"})
content = await response.aread()
print(content.decode())

// List files.
files, err := repo.ListFiles(ctx, storage.ListFilesOptions{})
if err != nil {
	return fmt.Errorf("list files: %w", err)
}
fmt.Println(files.Paths)

// List recent commits.
commits, err := repo.ListCommits(ctx, storage.ListCommitsOptions{Limit: 10})
if err != nil {
	return fmt.Errorf("list commits: %w", err)
}
for _, commit := range commits.Commits {
	fmt.Printf("%s %s\n", commit.SHA[:7], commit.Message)
}

// Read file content.
resp, err := repo.FileStream(ctx, storage.GetFileOptions{Path: "README.md"})
if err != nil {
	return fmt.Errorf("get file stream: %w", err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
	return fmt.Errorf("read file content: %w", err)
}
fmt.Println(string(body))

6. Apply a diff

Commit a unified diff to repo without a local clone.

const diff = `--- a/README.md
+++ b/README.md
@@
-# Quickstart
+# Quickstart project
`;

const patched = await repo.createCommitFromDiff({
  targetBranch: 'main',
  commitMessage: 'Apply upstream changes',
  diff,
  author: { name: 'Automation', email: 'bot@example.com' },
});

console.log(patched.commitSha);

diff = """\
--- a/README.md
+++ b/README.md
@@
-# Quickstart
+# Quickstart project
"""

patched = await repo.create_commit_from_diff(
    target_branch="main",
    commit_message="Apply upstream changes",
    diff=diff,
    author={"name": "Automation", "email": "bot@example.com"},
)

print(patched["commit_sha"])

diff := `--- a/README.md
+++ b/README.md
@@
-# Quickstart
+# Quickstart project
`

patched, err := repo.CreateCommitFromDiff(ctx, storage.CommitFromDiffOptions{
	TargetBranch:  "main",
	CommitMessage: "Apply upstream changes",
	Diff:          strings.NewReader(diff),
	Author:        storage.CommitSignature{Name: "Automation", Email: "bot@example.com"},
})
if err != nil {
	return fmt.Errorf("apply diff: %w", err)
}

fmt.Println(patched.CommitSHA)

Next steps

Git Operations: Use clone, fetch, push, and pull.
Ref Policies: Limit the refs that a token can update.
SDK Reference: Find methods for repositories, branches, commits, files, tags, and notes.
HTTP API: Use Code Storage without an SDK.

Getting Started

Features

Workflows

Reference

1. Install the SDK

2. Initialize the client

3. Create a repository

4. Create a commit

5. Read repository data

6. Apply a diff

Next steps

​1. Install the SDK

​2. Initialize the client

​3. Create a repository

​4. Create a commit

​5. Read repository data

​6. Apply a diff

​Next steps

1. Install the SDK

2. Initialize the client

3. Create a repository

4. Create a commit

5. Read repository data

6. Apply a diff

Next steps