Quickstart

Create a repository, push a commit, and browse it on the web. That is the whole loop.

1. Create an account

Open https://amendable.io/sign-up and create a free account.

The free plan includes:

5 active repositories
1 GiB stored Git data
5 GiB Git transfer per UTC month

You can stay on free while you try clone and push. Bring-your-own S3 needs Pro or Platform. See pricing.

2. Get an access token

You need a token for both the API and Git HTTPS.

cargo install --git https://github.com/LaunchPlatform/amendable-cli --locked
amendable login

The CLI prints a short code and a URL. Open the URL, confirm the code matches, and grant a token. The secret is stored in ~/.config/amendable/config.toml (mode 0600).

Then:

amendable whoami

Sign in and open Access tokens.
Click Create.
Leave Grant All Permissions checked (the default). That includes Git read/write and API_REPOS_WRITE.
Copy the token. Amendable shows it once.

Create access token: name agent, all repositories, Grant All Permissions checked.

Create the first token in the web UI. After that, a token with the ALL grant can mint narrower tokens:

export AMENDABLE_TOKEN='paste-the-token'
export AMENDABLE_API_URL='https://api.amendable.io'

curl -sS -X POST "$AMENDABLE_API_URL/v1/access-tokens" \
  -H "access-token: $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "laptop",
    "scope": "ALL_REPO",
    "grants": ["GIT_HTTP_READ", "GIT_HTTP_WRITE", "API_REPOS_WRITE"]
  }'

The JSON includes "token" only on create. Save it.

3. Create a repository

Names should be lowercase letters, numbers, hyphens, or underscores. The web form caps names at 32 characters. The API allows up to 64.

amendable repo create hello-amendable
amendable repo url hello-amendable

curl -sS -X POST https://api.amendable.io/v1/repositories \
  -H "access-token: $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "hello-amendable"}'

The response includes username and name. The clone URL is:

https://amendable.io/r/<username>/hello-amendable.git

import os
import httpx

api = os.environ.get("AMENDABLE_API_URL", "https://api.amendable.io")
token = os.environ["AMENDABLE_TOKEN"]
repo = httpx.post(
    f"{api}/v1/repositories",
    headers={"access-token": token},
    json={"name": "hello-amendable"},
)
repo.raise_for_status()
print(repo.json())

4. Clone, commit, push

Replace USER with your Amendable username.

amendable repo clone hello-amendable
cd hello-amendable
echo '# hello' > README.md
git add README.md
git commit -m "Initial commit"
git push -u origin main

The clone command uses your stored token, then rewrites origin to the clean HTTPS URL and sets credential.helper to amendable git-credential.

git clone "https://USER:${AMENDABLE_TOKEN}@amendable.io/r/USER/hello-amendable.git"
cd hello-amendable
echo '# hello' > README.md
git add README.md
git -c user.email="you@example.com" -c user.name="You" commit -m "Initial commit"
git push -u origin main
git remote set-url origin "https://amendable.io/r/USER/hello-amendable.git"

Putting the token in the remote URL leaks it into .git/config and shell history. Prefer the credential helper after the first clone.

Needs the CLI installed and a token in ~/.config/amendable/config.toml (run amendable login first). amendable must be on PATH so Git can spawn the helper.

git config --global credential.https://amendable.io.helper '!amendable git-credential'
git clone https://amendable.io/r/USER/hello-amendable.git
cd hello-amendable
echo '# hello' > README.md
git add README.md
git commit -m "Initial commit"
git push -u origin main

amendable git-credential reads username and token from ~/.config/amendable/config.toml.

After the push, open:

https://amendable.io/r/USER/hello-amendable

You should see README.md and the commit. Before the first push, the page looks like this:

Empty repository page with git clone, add, commit, and git push origin main.

amendable whoami --json

curl -sS https://api.amendable.io/v1/account/usage \
  -H "access-token: $AMENDABLE_TOKEN"

repos.used should be at least 1. Transfer bytes go up when you clone and push.

Clean up

amendable repo delete hello-amendable --yes

Or:

curl -sS -X DELETE \
  "https://api.amendable.io/v1/repos/USER/hello-amendable" \
  -H "access-token: $AMENDABLE_TOKEN"

Delete is a 204. The name can be reused after that.