cli-cloud-commands.mdx

title	Cloud commands
description	Authenticate with Agent Relay Cloud, connect providers, run workflows remotely, and sync patches back.

The cloud subcommands handle authentication, sandbox provider setup, remote workflow execution, and syncing code changes back to your machine.

Log in and inspect account state

agent-relay cloud login
agent-relay cloud whoami
agent-relay cloud logout

• login opens the browser-based cloud auth flow.
• whoami prints the current user, organization, workspace, and scopes.
• logout clears stored cloud credentials.

Connect a provider

agent-relay cloud connect claude --language typescript

This command opens an interactive SSH-backed auth session for a provider sandbox. It requires a real TTY. The CLI also accepts provider aliases:

• claude maps to anthropic
• codex maps to openai
• gemini maps to google

Run a workflow remotely

agent-relay cloud run relay.yaml --sync-code

Useful follow-up commands:

agent-relay cloud status <run-id>
agent-relay cloud logs <run-id> --follow
agent-relay cloud sync <run-id>

• status fetches the latest state for a run.
• logs streams workflow or per-agent output.
• sync downloads the generated patch and applies it locally.

--sync-code: uploading your local repo

--sync-code tarballs your current working copy and ships it to the cloud sandbox as the starting point for the run. Without it, the sandbox starts with no code on disk — it doesn't clone from origin, it just has an empty $HOME. Any workflow that reads your source needs --sync-code.

In almost every case, you want --sync-code. Running a workflow against an empty sandbox is rarely what you mean; you almost always want your local worktree state there.

What gets uploaded

The tarball is built from git ls-files — the tracked paths — and tar reads their current working-tree contents. No git clone anywhere.

State	Synced?
Committed, unmodified	✅ Working-tree version
Committed, then modified	✅ Working-tree version (your edits go too)
Committed, then modified + git added	✅ Working-tree version
New file + git added (not committed)	✅ — once added, the file is tracked
New file, never added	❌ Untracked → excluded
.gitignored path	❌ Excluded

Rule of thumb: git add whatever the run needs. Commit is NOT required — staging is enough because git ls-files returns indexed paths. You don't need to push either.

If you're not in a git repo at all, there's a fallback: the packer walks the filesystem and uses .gitignore as the exclude list.

When NOT to use --sync-code

Rare but real:

• You're running a cloud-managed workflow that doesn't touch local code (a fully config-typed workflow).
• You've set up a workflow whose setup-branch step explicitly git clones something and doesn't care about local state.

Typical flow

# Edit your workflow locally
vim workflows/fix-bug.ts

# Stage everything the run needs — `git add` is enough; commit is optional.
# Untracked files would be silently excluded otherwise.
git add workflows/fix-bug.ts

# Ship your working tree to the cloud sandbox and run
agent-relay cloud run workflows/fix-bug.ts --sync-code
# note the run ID printed...

# Stream logs as it runs
agent-relay cloud logs <run-id> --follow

# When complete, pull the produced diff back into your local worktree
agent-relay cloud sync <run-id>

See Workflows → Common mistakes for the "untracked files silently excluded" pitfall.

Inspect a patch before applying it

agent-relay cloud sync <run-id> --dry-run

Use --dir <path> if the patch should apply somewhere other than the current directory.

Deprecated alias

The top-level agent-relay connect <provider> command is deprecated. Use agent-relay cloud connect <provider> instead.

See also

Local workflow execution from the CLI. Conceptual overview of local versus cloud execution. Relayauth and credentials at the product level. Author the workflow files you submit to cloud.