> ## Documentation Index
> Fetch the complete documentation index at: https://code.storage/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> A quick look at how to set up your credentials and use the SDK to create a repository, commit files, and read repository data.

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.

## 1. Sign up and create a private key

* Create an account at [code.storage](https://code.storage).
* Create a new [Organization](https://code.storage/docs/platform/organizations.md) 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:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
export PIERRE_ORG="your-org"
export PIERRE_PRIVATE_KEY="$(cat /path/to/private-key.pem)"
```

See [Authentication](https://code.storage/docs/platform/authentication.md) 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`.

```bash TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
npm install @pierre/sdk
```

```bash Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
pip install pierre-sdk
```

```bash Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
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](https://code.storage/docs/sdks.md#create-a-client) for the client options.

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
import { Pierre } from '@pierre/sdk';
import { remoteUrl } from '@pierre/sdk/git';

const pierre = new Pierre();
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
from pierre import Pierre
from pierre.git import remote_url

pierre = Pierre()
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
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.

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
// 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
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
# 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}")
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
// 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](https://code.storage/docs/cli.md#pierre-auth-setup-git) 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](https://code.storage/docs/repos/github-sync.md) and [Generic Sync](https://code.storage/docs/repos/generic-sync.md).

## 5. Create a commit

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

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
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);
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
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"])
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
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`.

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
// 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());
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
# 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())
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
// 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.

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
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);
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
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"])
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
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)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.