guild workspace

Manage workspaces and their contents. Each subcommand has its own section below, in alphabetical order. Commands that take --workspace use your default workspace when you leave it out. Set the default with select.

guild workspace list                    # List all accessible workspaces
guild workspace select                  # Set the default workspace (interactive)
guild workspace current                 # Show the current default workspace
guild workspace chat                    # Chat with the Guild assistant

agent

Manage the agents installed in a workspace. Each command uses --workspace if you pass it, and your default workspace otherwise.

agent add

Install an agent in a workspace. By default, the installed agent updates automatically.

guild workspace agent add <agent>                     # Install an agent
guild workspace agent add <agent> --default           # Install and make it the default chat agent
guild workspace agent add <agent> --no-autoupdate     # Pin the installed version

Option	Description
`--default`	Set the agent as the workspace’s default chat agent.
`--no-autoupdate`	Turn off automatic updates for this agent.
`--workspace <id>`	The workspace ID or name.

Argument	Description
`<agent>`	The agent identifier, such as `owner~agent-name` or a UUID.

agent list

List the agents installed in a workspace.

guild workspace agent list
guild workspace agent list --workspace <id>

Option	Description
`--limit <number>`	The number of results to return. Defaults to `20`.
`--offset <number>`	The offset for pagination. Defaults to `0`.
`--workspace <id>`	The workspace ID or name.

agent remove

Remove an agent from a workspace.

guild workspace agent remove <agent>

Option	Description
`--workspace <id>`	The workspace ID or name.

Argument	Description
`<agent>`	The agent identifier, such as `owner~agent-name` or a UUID.

agent set-default

Set the workspace’s default chat agent. The agent must already be installed in the workspace.

guild workspace agent set-default <agent>            # Make an agent the default chat agent
guild workspace agent set-default <agent> --none     # Clear the default chat agent

Option	Description
`--none`	Clear the default chat agent instead of setting one.
`--workspace <id>`	The workspace ID or name.

Argument	Description
`<agent>`	The agent identifier, such as `owner~agent-name` or a UUID.

chat

Start a session with an agent in a workspace. Without --agent, you chat with the Guild assistant.

guild workspace chat                                   # Interactive chat with the Guild assistant
guild workspace chat "Summarize my open PRs"           # Start with an initial message
guild workspace chat --agent <identifier>              # Chat with a specific agent
guild workspace chat --workspace <identifier>          # Use a specific workspace
guild workspace chat --once "What is 2 + 2?"           # One-shot: send message and exit
guild workspace chat --resume <session-id>             # Resume a previous session (interactive or --once mode)
guild workspace chat --once --resume <session-id> "Another question"   # Resume a session in one-shot mode
guild workspace chat --events all                      # Include system and debug events

Option	Description
`--agent <identifier>`	The agent ID or full name, such as `foo~bar`. Defaults to the Guild assistant.
`--events <types>`	The event types to show. Use `none`, `user`, `system`, `all`, or a comma-separated list of type names such as `agent_console,llm_start`. Defaults to `user`.
`--no-splash`	Skip the splash screen animation.
`--once`	One-shot mode: send the message, wait for the response, and exit.
`--resume <session-id>`	Resume an existing session.
`--workspace <identifier>`	The workspace ID or full name, such as `owner~workspace-name`.

Argument	Description
`[prompt...]`	An optional initial prompt. It can be multiple words.

To chat with the agent you’re currently developing, use guild agent chat from inside the agent directory.

clear

Remove the default workspace setting from configuration.

guild workspace clear

Behavior depends on where you run the command:

In an agent directory (contains guild.json): removes workspace_id from guild.json and prints ✓ Cleared workspace setting for this agent.
Outside an agent directory: removes default_workspace and default_workspace_name from ~/.guild/config.json and prints ✓ Default workspace cleared.

If no default workspace is set, the command prints No default workspace was set. to stderr and exits successfully. It isn’t an error. Exit codes: 0 on success or no-op; 1 on filesystem error only.

context

Manage a workspace’s context versions. You edit context as a draft, then publish it.

context edit

Open the workspace context in your editor and save the result as a new draft version. By default, you start from the published version. The CLI uses $EDITOR, then $VISUAL, then $GIT_EDITOR, and fails if none is set.

guild workspace context edit <workspace>                       # Edit in $EDITOR, creates a draft
guild workspace context edit <workspace> --from <context-id>   # Edit from a specific version

The command prints the new draft’s ID and the publish command to run next.

Option	Description
`--from <context-id>`	Start from a specific context version instead of the published one.

Argument	Description
`<workspace>`	The workspace ID or full name, such as `owner~workspace-name`.

context get

Show a context version.

guild workspace context get <workspace> <context-id>

Argument	Description
`<workspace>`	The workspace ID or full name, such as `owner~workspace-name`.
`<context-id>`	The context ID.

context list

List a workspace’s context versions.

guild workspace context list <workspace>

Option	Description
`--limit <number>`	The number of results to return. Defaults to `20`.
`--offset <number>`	The offset for pagination. Defaults to `0`.

Argument	Description
`<workspace>`	The workspace ID or full name, such as `owner~workspace-name`.

context publish

Publish a draft context version.

guild workspace context publish <workspace> <context-id>

Argument	Description
`<workspace>`	The workspace ID or full name, such as `owner~workspace-name`.
`<context-id>`	The ID of the context version to publish.

create

Create a new workspace.

guild workspace create <name>                     # Create a new workspace
guild workspace create <name> --owner <owner>     # Create for a specific owner (name or ID)

Option	Description
`--owner <owner>`	The owner, as a name or ID.

Argument	Description
`<name>`	The workspace name.

current

Show the current default workspace and where it’s set: guild.json in the current agent directory, or ~/.guild/config.json.

guild workspace current

export

Export a workspace’s configuration to a JSON file. The export includes installed agents, time and webhook triggers, and the published context.

guild workspace export <identifier>                         # Write <workspace-name>.json
guild workspace export <identifier> --output backup.json    # Write to a specific path

If the workspace has triggers, the export includes their inputs as configured. Treat the file as sensitive if you entered secrets directly into trigger inputs or context.

Option	Description
`--output <path>`	The output file path. Defaults to `<workspace-name>.json`.

Argument	Description
`<identifier>`	The workspace ID, name, or full name.

get

Show a workspace’s details.

guild workspace get <identifier>

Argument	Description
`<identifier>`	The workspace ID or full name, such as `owner~workspace-name`.

import

Create a new workspace from a file made by export. The CLI installs the exported agents, recreates time triggers, and creates the context, publishing it if it was published in the export.

guild workspace import backup.json                          # Import with a confirmation prompt
guild workspace import backup.json --name my-copy --yes     # Import under a new name, skip the prompt

Webhook triggers are skipped, because they require organization-level integration setup. Agents that aren’t found or that you can’t access are skipped with a warning. In a non-interactive shell, you must pass --yes.

Option	Description
`--name <name>`	The name for the new workspace. Overrides the exported name.
`--owner <owner>`	The owner name or ID for the new workspace.
`--yes`	Skip the confirmation prompt.

Argument	Description
`<file>`	The path to the workspace export JSON file.

list

List the workspaces you can access, across every organization you belong to.

guild workspace list                       # List all accessible workspaces
guild workspace list --owner myorg         # Only workspaces owned by myorg

Option	Description
`--limit <number>`	The number of results to return. Defaults to `20`.
`--offset <number>`	The offset for pagination. Defaults to `0`.
`--owner <name>`	Filter workspaces by owner name, case-insensitively.

member

Restrict a workspace to an allow list of organization members. When restriction is on, only listed members and organization admins can access the workspace. Each command uses --workspace if you pass it, and your default workspace otherwise. To add or remove members, restriction must be on. Turn it on with member restrict --on.

member add

Add members to the workspace’s allow list. Each member must exactly match one eligible organization member by username, full name, or user ID.

guild workspace member add alice bob
guild workspace member add alice --workspace <id>

Option	Description
`--workspace <id>`	The workspace ID or name.

Argument	Description
`[members...]`	The usernames, full names, or user IDs to add. At least one is required.

member list

List the members on the workspace’s allow list.

guild workspace member list

Option	Description
`--limit <number>`	The number of results to return. Defaults to `20`.
`--offset <number>`	The offset for pagination. Defaults to `0`.
`--workspace <id>`	The workspace ID or name.

member remove

Remove members from the workspace’s allow list. Each member must exactly match one listed member.

guild workspace member remove alice

Option	Description
`--workspace <id>`	The workspace ID or name.

Argument	Description
`[members...]`	The usernames, full names, user IDs, or membership IDs to remove.

member restrict

Turn member restriction on or off. Pass exactly one of --on or --off.

guild workspace member restrict --on       # Only listed members and organization admins
guild workspace member restrict --off      # All organization members

Option	Description
`--off`	Turn off member restriction.
`--on`	Turn on member restriction.
`--workspace <id>`	The workspace ID or name.

member search

Search the organization members who are eligible for workspace access.

guild workspace member search              # List eligible members
guild workspace member search alice        # Search by username or full name

Option	Description
`--limit <number>`	The number of results to return. Defaults to `20`.
`--offset <number>`	The offset for pagination. Defaults to `0`.
`--workspace <id>`	The workspace ID or name.

Argument	Description
`[query]`	A search term for the username or full name.

select

Set the default workspace. In an agent directory (contains guild.json), it sets workspace_id in guild.json. Otherwise, it sets the default in ~/.guild/config.json.

guild workspace select                            # Choose interactively
guild workspace select <id-or-name>               # Set the default workspace directly
guild workspace select <name> --owner myorg       # Match only workspaces owned by myorg

Interactive selection requires a terminal. In a non-interactive shell, pass the workspace as an argument.

Option	Description
`--owner <name>`	Filter workspaces by owner name, case-insensitively.

Argument	Description
`[workspace]`	The workspace name or ID to select directly.

After a successful global workspace selection, guild workspace select prints to stderr: To clear the default, run: guild workspace clear. Pass --quiet to suppress it.

variable

Manage workspace variables: plain configuration values, not secrets. Each command uses --workspace if you pass it, and your default workspace otherwise. Keys must start with an uppercase letter and contain only uppercase letters, numbers, and underscores, up to 64 characters. Values can be up to 4096 characters.

variable delete

Delete a workspace variable.

guild workspace variable delete GITHUB_REPO

Option	Description
`--workspace <id-or-name>`	The workspace ID or name.

Argument	Description
`<key>`	The variable key.

variable get

Print a workspace variable’s value.

guild workspace variable get GITHUB_REPO

Option	Description
`--workspace <id-or-name>`	The workspace ID or name.

Argument	Description
`<key>`	The variable key.

variable list

List the variables set in a workspace.

guild workspace variable list
guild workspace variable list --workspace <id-or-name>

Option	Description
`--workspace <id-or-name>`	The workspace ID or name.

variable set

Set a workspace variable. The CLI splits the assignment on the first =, so the value can contain =.

guild workspace variable set GITHUB_REPO=guildaidev/guildcode    # Set a value
guild workspace variable set 'FLAGS=--foo --bar'                 # Quote values with spaces
guild workspace variable set EMPTY=                              # Set an empty value

Option	Description
`--workspace <id-or-name>`	The workspace ID or name.

Argument	Description
`<assignment>`	The variable assignment, in `KEY=VALUE` format.

​agent

​agent add

​agent list

​agent remove

​agent set-default

​chat

​clear

​context

​context edit

​context get

​context list

​context publish

​create

​current

​export

​get

​import

​list

​member

​member add

​member list

​member remove

​member restrict

​member search

​select

​variable

​variable delete

​variable get

​variable list

​variable set

agent

agent add

agent list

agent remove

agent set-default

chat

clear

context

context edit

context get

context list

context publish

create

current

export

get

import

list

member

member add

member list

member remove

member restrict

member search

select

variable

variable delete

variable get

variable list

variable set