Git Workflow

The Strayl CLI works on top of git. After running st init or st link, a git remote called strayl is added to your repository. All syncing happens through standard git operations with this remote.

Branches

Strayl uses two special branches:

You work on feature branches (any branch other than dev or main) and use st push to propose changes.

st push

Push a feature branch to Strayl and create a change proposal.

Copyst push

This is the primary command for proposing changes. It:

1. Pushes the current branch (or a specified branch) to the strayl remote
2. Creates a change proposal that appears in Manage → Updates in the web UI

Note: You cannot run st push on main or dev. Switch to a feature branch first.

Options

Examples

Copy# Push current branch with auto-generated title
st push
 
# Push with a custom title
st push --title "Add dark mode toggle"
 
# Push without creating a proposal (bare branch push)
st push --no-change

st pull

Pull the latest dev or main branch from Strayl into your local repository.

Copy# Pull from dev (default)
st pull
 
# Pull from main
st pull main

This runs git fetch strayl followed by git merge strayl/[branch]. Useful when the AI agent has made changes in the web UI and you want to continue locally.

st promote

Promote the dev branch to main, triggering a production deployment.

Copyst promote

This merges dev into main on the Strayl server. The production deployment is updated automatically.

Joining an existing project

If a project already exists on Strayl, clone it and start working right away:

Copyst clone alice/my-app
cd my-app
# You're on dev, ready to work

Typical workflow

Copy# 1. Pull the latest dev state
st pull
 
# 2. Create a feature branch
git checkout -b add-dark-mode
 
# 3. Make commits
git add .
git commit -m "Add dark mode toggle"
 
# 4. Push the branch and create a change proposal
st push --title "Add dark mode toggle"
 
# 5. Review the change in the browser, then approve it (merges into dev)
 
# 6. When ready to deploy to production
st promote

Conflict resolution

If your change has conflicts with dev (shown as needs_restack status), you can restack it from the CLI:

Copyst change <change-id> restack

Or resolve it manually:

Copy# Pull the latest dev
st pull
 
# Rebase your branch on dev
git rebase strayl/dev
 
# Re-push
st push