> ## 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](/docs/platform/organizations) 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](/docs/platform/authentication) for more details.

## 2. Install the SDK

<CodeGroup>
  ```bash TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  pnpm add @pierre/storage
  ```

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

  ```bash Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  go get github.com/pierrecomputer/sdk/packages/code-storage-go@latest
  ```
</CodeGroup>

See [SDK](/docs/sdk/overview) for more details.

## 3. Initialize the client

Pass `PIERRE_ORG` and `PIERRE_PRIVATE_KEY` to the client:

<CodeGroup>
  ```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  import { GitStorage } from '@pierre/storage';

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

  ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  import os

  from pierre_storage import GitStorage

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

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

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

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

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

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

To sync with GitLab, Bitbucket, or another HTTPS host, pass a base repository. See
[GitHub Sync](/docs/repos/github-sync) and [Generic Sync](/docs/repos/generic-sync).

## 5. Create a commit

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

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

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

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

## 6. Read repository data

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

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

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

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

## 7. Apply a diff

Commit a unified diff to `repo` without a local clone.

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

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

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