Quick Start

Learn how to use the Pierre SDK to create a repo, create a commit, read files, and apply diffs. These operations are some of the building blocks for agent workflows.

Create an account at code.storage.
Create a new Organization if needed (e.g., your-org)
Create a key on the organization’s Keys page.
Store the private key and set these environment variables. Replace your-org with your organization name:

export PIERRE_ORG="your-org"
export PIERRE_PRIVATE_KEY="$(cat /path/to/private-key.pem)"

See Authentication for more details.

2. Install the SDK

pnpm add @pierre/storage

pip install pierre-storage

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

See SDK for more details.

3. Initialize the client

Pass PIERRE_ORG and PIERRE_PRIVATE_KEY to the client:

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

const storage = 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"],
})

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

4. 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.

5. 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)

6. 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))

7. 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)

Getting Started

Platform

Workflows

Libraries

API Reference

2. Install the SDK

3. Initialize the client

4. Create a repository

5. Create a commit

6. Read repository data

7. Apply a diff

​1. Sign up and create a private key

​2. Install the SDK

​3. Initialize the client

​4. Create a repository

​5. Create a commit

​6. Read repository data

​7. Apply a diff

1. Sign up and create a private key

2. Install the SDK

3. Initialize the client

4. Create a repository

5. Create a commit

6. Read repository data

7. Apply a diff