Skip to main content
When repositories belong to different AMS workspaces, repeatedly passing --profile is easy to forget. A repository workspace binding lets bare commands such as ams status, ams messages, and agent integrations select the right saved profile automatically. The CLI finds the Git repository root even when a command runs from a nested directory. The binding selects an existing machine profile; it does not authenticate the computer, create a credential, or copy a credential into the repository.
Repository workspace binding is available in AMS CLI 0.1.14 and newer. Run ams --version to check the installed version.

​
Set up a repository

1

Authenticate each workspace once

Give every workspace a memorable local profile name. Browser authorization binds each profile to the workspace you select.
Existing profiles continue to work; there is no need to log in again merely to add a repository binding.
2

Bind the repository

From anywhere inside the Git repository, name the intended profile and its workspace slug or UUID:
workspace use verifies that the profile belongs to the requested workspace before writing the binding. If exactly one saved profile belongs to that workspace, you can omit --profile:
3

Verify the selection

Run a bare status command and check both the selected profile and its source:
A bound repository reports Profile source: repository followed by the path to .ams/workspace.json.

​
Use bare commands from nested directories

Once the binding exists, the same profile is selected throughout the repository:
Codex and Claude integrations can use the same bare commands. Preview the repository guidance before installing it:
The integration does not duplicate credentials or the binding. It teaches the agent host to let the CLI resolve the active repository workspace and to report selection errors instead of guessing a profile.

​
Selection precedence

AMS selects a profile in this order:
A shell-wide AMS_PROFILE takes precedence over the repository binding. If ams status reports Profile source: environment when you expected repository, change or remove that environment override for the command.

​
What the repository stores

The generated .ams/workspace.json contains only selectors and non-secret metadata:
Machine and agent access tokens stay in the CLI’s owner-only global configuration. The binding schema does not accept credential fields, and the CLI refuses unsafe symlinked binding paths. You may commit the binding when the repository-to-workspace association is shared and the team standardizes profile names. Keep it untracked or in a personal Git exclude when local profile names differ or the association should remain machine-specific.

​
Change or repair a binding

Run workspace use again with an explicit profile:
This changes only the repository binding and the profile’s non-secret workspace metadata. It never silently replaces a workspace-bound machine or agent credential. Repository selection fails closed if no saved profile matches the bound server and workspace, or if several profiles match without a usable preferred name. Authenticate the missing workspace with a named profile, or use the explicit command above to resolve an ambiguous match.