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

Install the SDK for your language: @pierre/sdk for TypeScript, pierre-sdk for Python, or the Go module github.com/pierrecomputer/sdk/go.

npm install @pierre/sdk

pip install pierre-sdk

go get github.com/pierrecomputer/sdk/go

3. Initialize the client

new Pierre() in TypeScript, Pierre() in Python, and pierre.NewClient() in Go read the same environment variables:

PIERRE_ORG: your organization name.
PIERRE_PRIVATE_KEY: your private key in PEM form. You can set PIERRE_PRIVATE_KEY_FILE to the path of the key file instead.
PIERRE_TOKEN: a fixed token. When it is set, the client sends it in place of a token that it signs with your key.
PIERRE_API_BASE_URL and PIERRE_GIT_HOST: other hosts in place of https://api.{org}.code.storage and {org}.code.storage.

With your private key, the client signs a 5-minute token for each request. Leave PIERRE_TOKEN unset for this guide, because step 4 signs a token for a Git remote URL, and a fixed token cannot do that. The Python examples use Pierre, the blocking client. AsyncPierre has the same methods for asyncio code. The code of steps 3 to 7 runs as one program, in page order. In TypeScript, put it in one ES module file: set "type": "module" in your package.json, or use a .mts file. See the SDK page for the client options.

import { Pierre } from '@pierre/sdk';
import { remoteUrl } from '@pierre/sdk/git';

const pierre = new Pierre();

from pierre import Pierre
from pierre.git import remote_url

pierre = Pierre()

import (
	"context"
	"fmt"
	"io"
	"strings"
	"time"

	pierre "github.com/pierrecomputer/sdk/go"
	"github.com/pierrecomputer/sdk/go/git"
)

ctx := context.Background()
client, err := pierre.NewClient()
if err != nil {
	return fmt.Errorf("create client: %w", err)
}

4. Create a repository

Each repository belongs to your organization and has a unique name. Code Storage can generate a UUID, or you can supply a name such as team/project-alpha. A new repository uses main as its default branch, but it has no branch until its first commit. Step 5 creates main. A synced repository takes the default branch of its upstream.

// Create a repository with a server-generated name.
const generatedRepo = await pierre.repos.create();
console.log(generatedRepo.repo_name); // e.g. '123e4567-e89b-12d3-a456-426614174000'

// Or create a repository with your own name.
const repo = await pierre.repos.create({ repo_name: 'quickstart' });

// Or create a repository that syncs from a public GitHub repository.
const syncedRepo = await pierre.repos.create({
  repo_name: 'hello-world',
  upstream: { provider: 'github', owner: 'octocat', name: 'Hello-World', access: 'public' },
});
console.log(syncedRepo.repo_name);

// Get a Git remote URL with a token that lives 1 hour.
const url = await remoteUrl(pierre, { repo_name: repo.repo_name, ttl: 3600 });
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 name.
generated_repo = pierre.repos.create()
print(generated_repo["repo_name"])  # e.g. '123e4567-e89b-12d3-a456-426614174000'

# Or create a repository with your own name.
repo = pierre.repos.create(repo_name="quickstart")

# Or create a repository that syncs from a public GitHub repository.
synced_repo = pierre.repos.create(
    repo_name="hello-world",
    upstream={"provider": "github", "owner": "octocat", "name": "Hello-World", "access": "public"},
)
print(synced_repo["repo_name"])

# Get a Git remote URL with a token that lives 1 hour.
url = remote_url(pierre, repo_name=repo["repo_name"], ttl=3600)
print(f"git remote add origin {url}")

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

// Or create a repository with your own name.
repo, err := client.Repos.Create(ctx, pierre.ReposCreateParams{
	RepoName: pierre.String("quickstart"),
})
if err != nil {
	return fmt.Errorf("create repository: %w", err)
}

// Or create a repository that syncs from a public GitHub repository.
syncedRepo, err := client.Repos.Create(ctx, pierre.ReposCreateParams{
	RepoName: pierre.String("hello-world"),
	Upstream: pierre.Value(pierre.UpstreamConfig{
		Provider: pierre.UpstreamConfigProviderGithub,
		Owner:    "octocat",
		Name:     "Hello-World",
		Access:   pierre.Value(pierre.UpstreamConfigAccessPublic),
	}),
})
if err != nil {
	return fmt.Errorf("create synced repository: %w", err)
}
fmt.Println(syncedRepo.RepoName)

// Get a Git remote URL with a token that lives 1 hour.
url, err := git.RemoteURL(ctx, client, git.RemoteURLParams{RepoName: repo.RepoName, TTL: time.Hour})
if err != nil {
	return fmt.Errorf("create remote URL: %w", err)
}
fmt.Printf("git remote add origin %s\n", url)

The remote URL holds a token, so do not write it to a log that other people can read. The token expires after 1 hour, the longest lifetime that the SDK allows. For Git work that lasts longer, use the credential helper of the CLI. A public GitHub repository needs no GitHub App. To sync a private GitHub repository, or a repository on GitLab, Bitbucket, or another HTTPS host, pass a different upstream. See GitHub Sync and Generic Sync.

5. Create a commit

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

const result = await pierre.repos.commits.create({
  repo_name: repo.repo_name,
  target_branch: 'main',
  commit_message: 'Initial commit',
  author: { name: 'Your Name', email: 'you@example.com' },
  files: [{ path: 'README.md', content: '# Quickstart\n' }],
});

console.log(result.commit.commit_sha);

result = pierre.repos.commits.create(
    repo_name=repo["repo_name"],
    target_branch="main",
    commit_message="Initial commit",
    author={"name": "Your Name", "email": "you@example.com"},
    files=[{"path": "README.md", "content": "# Quickstart\n"}],
)

print(result["commit"]["commit_sha"])

result, err := client.Repos.Commits.Create(ctx, pierre.ReposCommitsCreateParams{
	RepoName:      repo.RepoName,
	TargetBranch:  "main",
	CommitMessage: "Initial commit",
	Author:        pierre.GitIdentity{Name: "Your Name", Email: "you@example.com"},
	Files: []pierre.CommitFile{
		{Path: "README.md", Content: strings.NewReader("# Quickstart\n")},
	},
})
if err != nil {
	return fmt.Errorf("create commit: %w", err)
}

fmt.Println(result.Commit.CommitSHA)

6. Read repository data

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

// List files.
const files = await pierre.repos.files.list({ repo_name: repo.repo_name });
console.log(files.body.paths);

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

// Read file content.
const response = await pierre.repos.files.get({ repo_name: repo.repo_name, path: 'README.md' });
console.log(await response.text());

# List files.
files = pierre.repos.files.list(repo_name=repo["repo_name"])
print(files.body["paths"])

# List recent commits.
commits = pierre.repos.commits.list(repo_name=repo["repo_name"], limit=10)
for commit in commits.data:
    print(f"{commit['sha'][:7]} {commit['message']}")

# Read file content.
response = pierre.repos.files.get(repo_name=repo["repo_name"], path="README.md")
content = response.read()
response.close()
print(content.decode())

// List files.
files, err := client.Repos.Files.List(ctx, pierre.ReposFilesListParams{RepoName: repo.RepoName})
if err != nil {
	return fmt.Errorf("list files: %w", err)
}
fmt.Println(files.Body.Paths)

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

// Read file content.
file, err := client.Repos.Files.Get(ctx, pierre.ReposFilesGetParams{
	RepoName: repo.RepoName,
	Path:     "README.md",
})
if err != nil {
	return fmt.Errorf("get file: %w", err)
}
defer file.Close()
body, err := io.ReadAll(file)
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
@@ -1 +1 @@
-# Quickstart
+# Quickstart project
`;

const patched = await pierre.repos.commits.createFromDiff({
  repo_name: repo.repo_name,
  target_branch: 'main',
  commit_message: 'Apply upstream changes',
  diff,
  author: { name: 'Automation', email: 'bot@example.com' },
});

console.log(patched.commit.commit_sha);

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

patched = pierre.repos.commits.create_from_diff(
    repo_name=repo["repo_name"],
    target_branch="main",
    commit_message="Apply upstream changes",
    diff=diff,
    author={"name": "Automation", "email": "bot@example.com"},
)

print(patched["commit"]["commit_sha"])

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

patched, err := client.Repos.Commits.CreateFromDiff(ctx, pierre.ReposCommitsCreateFromDiffParams{
	RepoName:      repo.RepoName,
	TargetBranch:  "main",
	CommitMessage: "Apply upstream changes",
	Diff:          strings.NewReader(diff),
	Author:        pierre.GitIdentity{Name: "Automation", Email: "bot@example.com"},
})
if err != nil {
	return fmt.Errorf("apply diff: %w", err)
}

fmt.Println(patched.Commit.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