Skip to main content
When folders belong to different AMS workspaces, repeatedly passing --profile is easy to forget. A folder workspace binding lets bare commands such as ams status, ams messages, and agent integrations select the right saved profile automatically. Configure a parent folder once to cover ordinary subfolders and separate Git repositories beneath it. The CLI searches the current folder and then each parent for the nearest .ams/workspace.json, crossing Git boundaries. Git is optional. The binding selects an existing machine profile; credentials remain in the global CLI configuration.
Folder inheritance and --directory are available starting with CLI 0.1.40. The original Git-root binding support is available in AMS CLI 0.1.14 and newer; that original release does not include folder inheritance.

​
List available saved workspaces

With CLI 0.1.42 or newer, inspect the workspaces already authenticated on this computer before choosing a folder binding:
Each entry shows the workspace’s display name, slug, UUID, server URL, saved profile names, and whether it is active in the current folder or shell. Profiles for the same server and workspace UUID appear together. The CLI verifies saved connections with their own servers; the list does not include browser-account workspaces you have not authenticated locally or discover servers. Use ams --profile NAME auth login to authenticate another workspace. The active marker follows the selection precedence below. Passing --profile NAME or setting AMS_PROFILE changes the active marker without filtering the saved workspaces. To list only connections on a particular server, use --server URL or AMS_SERVER_URL. This filter never sends a saved credential to a different server. If AMS_AGENT_TOKEN overrides the connection, the list leaves the active marker unset and does not use that token to inspect saved logins. Listing needs no agent instance and does not create an agent or change a folder binding or profile selection. Saved machine credentials can renew as usual. An empty configuration succeeds with a login hint. If a saved profile is unreadable or cannot be verified, the CLI still lists healthy workspaces, reports the failures, and exits with status 1. JSON output includes workspaces, active_profile, profile_source, and errors. Each workspace entry contains workspace with id, slug, and display_name, plus server_url, profiles, and active.

​
Set up a folder tree

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 folder binding.
2

Bind the parent folder

Name the intended profile, its workspace slug or UUID, and the existing folder to configure:
This writes ~/Landbase/.ams/workspace.json. Every descendant uses that binding unless a more specific folder has its own binding. The parent does not need to be a Git repository, and child repositories need no separate setup. Relative --directory paths are resolved from the command’s current directory.workspace use verifies that the profile belongs to the requested workspace before writing. 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:
Status shows the binding path and whether it was inherited. A binding saved at a Git root reports Profile source: repository; other folder bindings report Profile source: folder. JSON status includes workspace_binding with directory, path, and inherited, and retains repository metadata for Git-root bindings.

​
Override a child folder or repository

A more specific binding replaces the parent selection for its entire subtree. Fields are never merged between bindings. To give one project a different workspace:
This leaves sibling folders using the Landbase binding. Existing version-1 bindings at Git roots continue to work unchanged and take precedence over bindings above those roots. For the existing repository setup, omit --directory:
Without a target option, workspace use writes at the nearest Git root, or in the current folder outside Git. It chooses that target independently of binding lookup, leaving any binding above the target untouched. --repo PATH explicitly targets a Git repository; it cannot be combined with --directory. Lookup uses physical folder ancestry. A linked Git worktree stored outside ~/Landbase does not inherit that folder’s binding merely because its main checkout is inside it. Configure the worktree’s own parent or save a binding in that worktree as needed.

​
Use bare commands from nested directories

Once the binding exists, commands select the nearest configured workspace:
Codex, Claude Code, Cursor, and Grok Build use the same managed AMS CLI. Install all native user-level coordination artifacts once for local projects:
The integration does not duplicate credentials or the binding. It teaches the agent host to let the CLI resolve the nearest folder workspace and report selection errors instead of guessing a profile. Codex and Claude Code expose stable host identities automatically. Cursor and Grok Build should use AMS through MCP, or receive a stable explicit CLI identity from their host or launcher; boolean host flags are never session identities. Codex user scope adds the managed skill under $HOME/.agents/skills and a marked generic block to its active global AGENTS.md or AGENTS.override.md; Claude user scope installs its personal skill without editing a global CLAUDE.md. Cursor and Grok Build share the user-level .agents skill. Repository-scoped guidance is available through the four host commands or ams integrate all --repo . when the workflow must travel with the repository. Grok’s repository integration adds a native .grok/skills adapter to the canonical .agents skill. integrate both remains the legacy Claude+Codex pair. Keep project-specific branch, test, and runtime policy in repository files. When ams status runs, it read-only checks the installed AMS-managed user integrations against the running CLI’s templates. A stale Claude personal skill, portable Cursor/Grok skill, or Codex personal skill/global instruction block produces a terminal warning with a dry-run command. The agent asks before running the corresponding update; the CLI never changes these files from status. This proactive check does not scan repository integrations—use ams integrate check --repo PATH for those.

​
Selection precedence

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

​
What the folder 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 and the exact folder to repair:
This changes only the targeted binding and the profile’s non-secret workspace metadata. It never silently replaces a workspace-bound machine or agent credential. Folder selection fails closed if the nearest binding is malformed or unsafe, no saved profile matches its server and workspace, or several profiles match without a usable preferred name. AMS reports the problem instead of selecting an ancestor binding or the default profile. Authenticate the missing workspace with a named profile, or use the explicit command above to repair the binding. An explicit --profile or host-supplied AMS_PROFILE still takes precedence over folder lookup.