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

# Quickstart

> Install the SDK, create your first repository, and start storing code in minutes. This guide walks you through the essential setup—from authentication to your first git clone.

The fastest way to get up and running is with the [**Code Storage SDK**](/reference/sdk), available for TypeScript, Python, and Go. Before getting
started head to the dashboard to generate a `private key` and make note of your organization's
`name` identifier.

1. Install the SDK:

   <CodeGroup>
     ```bash TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     pnpm i @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>

2. Initialize the client:

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

     const store = new GitStorage({
       name: 'your-org',    // Your organization identifier
       key: env.privateKey, // Your API key
     });
     ```

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

     storage = GitStorage({
         "name": "your-name", # e.g., 'v0'
         "key": "your-key",   # Your API key in PEM format
     })
     ```

     ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     client, err := storage.NewClient(storage.Options{
         Name: "your-org",
         Key:  os.Getenv("PIERRE_PRIVATE_KEY"),
     })
     if err != nil {
         return fmt.Errorf("failed to create client: %w", err)
     }
     ```
   </CodeGroup>

3. Create and use a repository:

   <CodeGroup>
     ```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     // Create a new repository
     const repo = await store.createRepo();

     // Get a secure Git URL with authentication
     const url = await repo.getRemoteURL();

     // Configure Git to use the repository
     console.log(`git remote add origin ${url}`);
     // Output: git remote add origin https://t:JWT@[org].code.storage/repo-id.git
     ```

     ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     # Create a new repository with auto-generated ID
     repo = await storage.create_repo()
     print(repo.id)  # e.g., '123e4567-e89b-12d3-a456-426614174000'

     # Create a repository with a custom ID
     custom_repo = await storage.create_repo(id="my-custom-repo")
     print(custom_repo.id)  # 'my-custom-repo'

     # Create a repository with GitHub App sync.
     # For GitLab, Bitbucket, and other providers, use the `provider` field instead.
     # See: /guides/integrations
     github_repo = await storage.create_repo(
         id="my-synced-repo",
         base_repo={
             "owner": "octocat",
             "name": "Hello-World",
             "default_branch": "main",  # optional
         },
     )

     # This repository will sync with github.com/octocat/Hello-World
     # Get a secure Git URL and configure Git
     secure_url = await repo.get_remote_url()
     print(f"git remote add origin {secure_url}")
     ```

     ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     ctx := context.Background() // or from an existing context

     // Create a repository with auto-generated ID
     repo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{})
     if err != nil {
         return fmt.Errorf("failed to create repository: %w", err)
     }
     fmt.Println("Repository ID:", repo.ID)

     // Create a repository with a custom ID
     customRepo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
         ID: "my-custom-repo",
     })
     if err != nil {
         return fmt.Errorf("failed to create repository: %w", err)
     }

     // Create a repository with GitHub App sync.
     // For GitLab, Bitbucket, and other providers, use storage.GenericGitBaseRepo instead.
     // See: /guides/integrations
     githubRepo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
         ID: "my-synced-repo",
         BaseRepo: storage.GitHubBaseRepo{
             Owner:         "octocat",
             Name:          "Hello-World",
             DefaultBranch: "main",
         },
     })
     if err != nil {
         return fmt.Errorf("failed to create repository: %w", err)
     }

     // Get a secure Git URL and configure Git
     remoteURL, err := repo.RemoteURL(ctx, storage.RemoteURLOptions{})
     if err != nil {
         return fmt.Errorf("failed to get remote URL: %w", err)
     }
     err = exec.Command("git", "remote", "add", "origin", remoteURL).Run()
     if err != nil {
         return fmt.Errorf("failed to add new remote: %w", err)
     }
     ```
   </CodeGroup>

   See [Integrations](/guides/integrations) for provider-specific setup, including GitHub App sync,
   public GitHub mode, and generic HTTPS Git providers.

4. Make your first commit:

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

     async function main() {
       const store = new GitStorage({
         name: 'your-name',
         key: env.privateKey,
       });

       const repo = await store.createRepo();
       console.log(`Created repository: ${repo.id}`);

       const url = await repo.getRemoteURL();
       console.log(`Git URL: ${url}`);

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

       console.log(`Commit SHA: ${result.commitSha}`);
     }
     ```

     ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     import asyncio
     from pierre_storage import GitStorage

     async def main():
         # Initialize the client
         storage = GitStorage({
             "name": "your-name",
             "key": """-----BEGIN PRIVATE KEY-----
             Your private key here
             -----END PRIVATE KEY-----""",
         })

         # Create a repository
         repo = await storage.create_repo()
         print(f"Created repository: {repo.id}")

         # Get the Git remote URL
         url = await repo.get_remote_url()
         print(f"Git URL: {url}")

         # Create your first commit
         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", "# My Project\n\nWelcome!")
             .send()
         )

         print(f"Commit SHA: {result['commit_sha']}")

     # Run the example
     asyncio.run(main())
     ```

     ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     // Initialize the client
     client, err := storage.NewClient(storage.Options{
         Name: "your-name",
         Key:  os.Getenv("PIERRE_PRIVATE_KEY"),
     })

     ctx := context.Background() // or from an existing context
     repo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{})
     if err != nil {
         return fmt.Errorf("failed to create repository: %w", err)
     }
     fmt.Println("Repository ID:", repo.ID)

     remoteURL, err := repo.RemoteURL(ctx, storage.RemoteURLOptions{})
     if err != nil {
         return fmt.Errorf("failed to get remote URL: %w", err)
     }
     fmt.Println("Remote URL:", remoteURL)

     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("failed to create commit: %w", err)
     }

     result, err := builder.
         AddFileFromString("README.md", "# My Project\n\nWelcome!", nil).
         Send(ctx)
     if err != nil {
         return fmt.Errorf("failed to add file: %w", err)
     }
     fmt.Println("Commit SHA:", result.CommitSHA)
     ```
   </CodeGroup>

5. Read repository data:

   <CodeGroup>
     ```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     async function readData() {
         const store = new GitStorage({ name: 'your-name', key: env.privateKey });
         const repo = await store.findOne({ id: 'repo-id' });

         if (!repo) return;

         // List files
         const files = await repo.listFiles();
         console.log('Files:', files.paths);

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

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

     ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     async def read_data():
         storage = GitStorage({"name": "your-name", "key": "your-key"})
         repo = await storage.find_one({"id": "repo-id"})

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

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

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

     asyncio.run(read_data())
     ```

     ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     ctx := context.Background() // or from an existing context
     repo, err := client.FindOne(ctx, storage.FindOneOptions{ID: "repo-id"})
     if err != nil {
         return fmt.Errorf("failed to find repository: %w", err)
     } else if repo == nil {
         return nil // nil means not found
     }

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

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

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

6. Apply an existing diff:

   <CodeGroup>
     ```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     async function applyDiff() {
         const store = new GitStorage({ name: 'your-name', key: env.privateKey });
         const repo = await store.findOne({ id: 'repo-id' });

         if (!repo) return;

         const diffText = `--- a/README.md
     +++ b/README.md
     @@
     -Old line
     +New line
     `;

         const result = await repo.createCommitFromDiff({
         targetBranch: 'main',
         commitMessage: 'Apply upstream changes',
         diff: diffText,
         author: { name: 'Automation', email: 'bot@example.com' },
         baseBranch: 'main', // optional, matches createCommit options
         });

         console.log(`Updated commit: ${result.commitSha}`);
     }
     ```

     ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     async def apply_diff():
         storage = GitStorage({"name": "your-name", "key": "your-key"})
         repo = await storage.find_one({"id": "repo-id"})

         diff_text = """\
     --- a/README.md
     +++ b/README.md
     @@
     -Old line
     +New line
     """

         result = await repo.create_commit_from_diff(
             target_branch="main",
             commit_message="Apply upstream changes",
             diff=diff_text,
             author={"name": "Automation", "email": "bot@example.com"},
             base_branch="main",  # optional, matches create_commit options
         )

         print(f"Updated commit: {result['commit_sha']}")

     asyncio.run(apply_diff())
     ```

     ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
     ctx := context.Background() // or from an existing context
     repo, err := client.FindOne(ctx, storage.FindOneOptions{ID: "repo-id"})
     if err != nil {
         return fmt.Errorf("failed to find repository: %w", err)
     } else if repo == nil {
         return nil // nil means not found
     }

     const diffText = `--- a/README.md
     +++ b/README.md
     @@
     -Old line
     +New line
     `
     result, err := repo.CreateCommitFromDiff(ctx, storage.CommitFromDiffOptions{
         TargetBranch:  "main",
         CommitMessage: "Apply upstream changes",
         Diff:          strings.NewReader(diffText),
         Author:        storage.CommitSignature{Name: "Automation", Email: "bot@example.com"},
         BaseBranch:    "main",
     })
     if err != nil {
         return fmt.Errorf("failed to create commit: %w", err)
     }
     fmt.Println("Updated commit:", result.CommitSHA)
     ```
   </CodeGroup>