Getting Started

Install the SDK and read a file from a repo in under 2 minutes.

Quickstart

pip install githosted

from githosted import Client

client = Client(token="gw_your_workspace_token")
repo = client.repo("my-project")

files = repo.ls("src/")
print(files)
# [FileEntry(name='main.py', type='file'), FileEntry(name='lib', type='directory')]

file = repo.read("src/main.py")
print(file.content)
# "print('hello')"

Installation

pip install githosted

The only runtime dependency is httpx. Python 3.10+ is required.

Authentication

The SDK needs a workspace token (gw_) or repo token (gr_). Pass it directly or set the GITHOSTED_TOKEN environment variable:

export GITHOSTED_TOKEN=gw_your_workspace_token

# Explicit token
client = Client(token="gw_xxx")

# Auto-reads GITHOSTED_TOKEN from env
client = Client()

See Authentication for the full credential resolution order.

Reading and Writing

repo = client.repo("my-project")

# Read a file
file = repo.read("README.md")
print(file.content)       # file contents as string
print(file.head_sha)      # branch tip SHA — use for optimistic concurrency

# Write a file
repo.write("README.md", "# Updated readme", "Update readme")

# Atomic multi-file commit
with repo.transaction("Add feature") as tx:
    tx.write("src/feature.py", feature_code)
    tx.write("tests/test_feature.py", test_code)

Using Repo IDs

Repos have stable IDs (rp_ prefix) that don’t change on rename. You can reference repos by slug or ID:

# By slug
repo = client.repo("my-project")

# By stable ID — preferred for persistence
repo = client.repo(id="rp_8f3k2m1q9t6w4z7c5n2h")

Next Steps

• Reading and Writing Files
• Atomic Transactions
• Error Handling