> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idyl.network/llms.txt
> Use this file to discover all available pages before exploring further.

# idyl workspace

> Manage workspaces in a namespace

View and manage the Workspaces of a Namespace.

A Workspace is a focused logical computer with durable files, Runs, sessions,
history, and artifacts. Workspace names are unique within their Namespace. A
Workspace is created deliberately; Accounts do not receive a default one.

## Usage

```bash theme={null}
idyl workspace
```

## Aliases

* `workspaces`
* `ws`

## Commands

| Command                 | Description                                  |
| ----------------------- | -------------------------------------------- |
| `idyl workspace create` | Create a workspace                           |
| `idyl workspace delete` | Delete a workspace                           |
| `idyl workspace get`    | Get workspace details or list all workspaces |
| `idyl workspace list`   | List workspaces                              |

## Inherited flags

| Flag                                 | Description                                                        |
| ------------------------------------ | ------------------------------------------------------------------ |
| `-a <string>, --account-id <string>` | Account ID to use, overriding the current context.                 |
| `-c <string>, --context <string>`    | Use the named context for this command.                            |
| `--homedir <string>`                 | Override the configuration directory. Defaults to \~/.config/idyl. |
| `-n <string>, --namespace <string>`  | Namespace to address, overriding the entered context.              |
| `--network <string>`                 | Override the Network for this command.                             |
| `-p <string>, --profile <string>`    | Override the access profile for this command.                      |
| `-s <string>, --subnet <string>`     | Subnet to use for this command, overriding the current context.    |
| `--workspace <string>`               | Workspace within the namespace, overriding the entered context.    |

## Examples

```bash theme={null}
# List workspaces
idyl workspace list

# Create a workspace and enter it
idyl workspace create payments
idyl use production/payments

 # Show one workspace
idyl ws get payments

 # Delete a workspace
idyl workspace delete payments
```

## Subcommand reference

### `idyl workspace create`

Create a Workspace in the resolved Namespace.

Creating a Workspace creates a logical computer. It does not create a
Namespace, and it does not enter the Workspace automatically.

#### Usage

```bash theme={null}
idyl workspace create <name> [flags]
```

#### Flags

| Flag                             | Description                                         |
| -------------------------------- | --------------------------------------------------- |
| `--description <string>`         | Description of the workspace.                       |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`. |

#### Examples

```bash theme={null}
# Create a workspace
idyl workspace create payments

# Create with a description
idyl ws create payments --description "Payments platform"

# Create and enter it
 idyl workspace create payments --namespace production
 idyl use production/payments
```

### `idyl workspace delete`

Delete a Workspace from the resolved Namespace.

Deletion is asynchronous. The platform accepts it, records the Workspace as
terminating, stops the Workloads of its Runs, removes its files, revisions,
Runs, and attempts, and finalizes on its own; once finalized the name no
longer resolves and may be reused. Nothing else in the Namespace is touched.
While it is terminating the Workspace still reads, and creating or editing
anything in it is refused. Deleting a Workspace that is already terminating
is accepted again.

\--wait blocks until the Workspace is finalized and exits the way 'idyl wait'
does: 0 finalized, 124 when --timeout passes first. Without it the command
returns as soon as the deletion is accepted.

You will be prompted for confirmation unless the --yes flag is provided.

#### Usage

```bash theme={null}
idyl workspace delete <name> [flags]
```

#### Aliases

* `rm`

#### Flags

| Flag                   | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `--timeout <duration>` | Maximum time to block with --wait; 0s checks the current state once. Default: `5m0s`. |
| `--wait`               | Block until the workspace is finalized, exiting the way 'idyl wait' does.             |
| `-y, --yes`            | Skip confirmation prompts.                                                            |

#### Examples

```bash theme={null}
# Delete a workspace (with confirmation)
idyl workspace delete payments

# Delete without confirmation
idyl ws delete payments --yes

# Delete and block until the workspace is finalized
idyl workspace delete payments --yes --wait
```

### `idyl workspace get`

Get details of a Workspace, or list Workspaces in the resolved Namespace.

With no arguments, lists all workspaces.
With a name argument, shows that Workspace.
-A/--all-namespaces lists across every namespace in the account; a named
Workspace requires its Namespace, so a name is rejected with it.

#### Usage

```bash theme={null}
idyl workspace get [name] [flags]
```

#### Flags

| Flag                             | Description                                          |
| -------------------------------- | ---------------------------------------------------- |
| `-A, --all-namespaces`           | List across every namespace in the account.          |
| `--limit <int>`                  | Maximum number of workspaces to list. Default: `20`. |
| `--offset <int>`                 | Number of workspaces to skip. Default: `0`.          |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`.  |

#### Examples

```bash theme={null}
# List workspaces
idyl workspace get

# List workspaces in every namespace in the account
idyl workspace get -A

# Show one workspace
idyl workspace get payments

# Show it as JSON
idyl ws get payments -o json
```

### `idyl workspace list`

List the Workspaces in the resolved Namespace.

The entered workspace is marked. -A/--all-namespaces lists across every
namespace in the account with a NAMESPACE column; it cannot be combined
with --namespace or --workspace.

#### Usage

```bash theme={null}
idyl workspace list [flags]
```

#### Aliases

* `ls`

#### Flags

| Flag                             | Description                                          |
| -------------------------------- | ---------------------------------------------------- |
| `-A, --all-namespaces`           | List across every namespace in the account.          |
| `--limit <int>`                  | Maximum number of workspaces to list. Default: `20`. |
| `--offset <int>`                 | Number of workspaces to skip. Default: `0`.          |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`.  |

#### Examples

```bash theme={null}
# List workspaces
idyl workspace list

# List workspaces in every namespace in the account
idyl workspace list -A

# List as JSON
idyl ws list -o json
```