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

# Menu System

> Powerful menu configuration with nested structures, aliases, and interactive forms

The dx menu system is the heart of your terminal workflow, allowing you to organize commands, files, and interactive forms in a hierarchical structure.

## Configuration Formats

dx supports multiple configuration formats for maximum flexibility:

<Tabs>
  <Tab title="YAML">
    ```yaml theme={null}
    items:
      - name: Build Project
        description: Compile and build the project
        cmd: cargo build --release
        alias: build
    ```
  </Tab>

  <Tab title="TOML">
    ```toml theme={null}
    [[items]]
    name = "Build Project"
    description = "Compile and build the project"
    cmd = "cargo build --release"
    alias = "build"
    ```
  </Tab>

  <Tab title="JSON">
    ```json theme={null}
    {
      "items": [
        {
          "name": "Build Project",
          "description": "Compile and build the project", 
          "cmd": "cargo build --release",
          "alias": "build"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Auto-Detection

dx automatically searches for menu files in this priority order:

1. `dx.yaml`, `dx.yml`, `dx.toml`, `dx.json`
2. `menu.yaml`, `menu.yml`, `menu.toml`, `menu.json`

## Item Types

<CardGroup cols={2}>
  <Card title="Commands" icon="terminal">
    Execute shell commands with full PTY support
  </Card>

  <Card title="Files" icon="file">
    Display files with rich Markdown rendering
  </Card>

  <Card title="Nested Menus" icon="folder">
    Organize items in hierarchical structures
  </Card>

  <Card title="Interactive Forms" icon="wpforms">
    Collect user input with dynamic field validation
  </Card>
</CardGroup>

## Aliases for CLI Access

```bash theme={null}
dx build        # Run aliased command directly
dx test         # Execute test suite 
dx aliases      # List all available aliases
```

## Advanced Features

### Nested Menu Structure

Create organized hierarchies with unlimited depth:

<CodeGroup>
  ```yaml dx.yaml theme={null}
  items:
    - name: "Development Tools"
      description: "Build, test, and deploy commands"
      children:
        - name: "Build Release"
          cmd: "cargo build --release"
          alias: "build"
        - name: "Run Tests"
          cmd: "cargo test"
          alias: "test"
  ```

  ```toml dx.toml theme={null}
  [[items]]
  name = "Development Tools"
  description = "Build, test, and deploy commands"

  [[items.children]]
  name = "Build Release"
  cmd = "cargo build --release" 
  alias = "build"

  [[items.children]] 
  name = "Run Tests"
  cmd = "cargo test"
  alias = "test"
  ```

  ```json dx.json theme={null}
  {
    "items": [
      {
        "name": "Development Tools",
        "description": "Build, test, and deploy commands",
        "children": [
          {
            "name": "Build Release",
            "cmd": "cargo build --release",
            "alias": "build"
          },
          {
            "name": "Run Tests",
            "cmd": "cargo test",
            "alias": "test"
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

### Interactive Forms

Build dynamic forms that collect input and execute commands:

<CodeGroup>
  ```yaml dx.yaml theme={null}
  items:
    - name: "Deploy Application"
      description: "Deploy to specified environment"
      form:
        title: "Application Deployment"
        fields:
          - name: "environment"
            label: "Target Environment"
            type: "select"
            options: ["staging", "production"]
          - name: "version"
            label: "Version Tag"
            placeholder: "v1.0.0"
        submit: "deploy.sh {environment} {version}"
  ```

  ```toml dx.toml theme={null}
  [[items]]
  name = "Deploy Application"
  description = "Deploy to specified environment"

  [items.form]
  title = "Application Deployment"
  submit = "deploy.sh {environment} {version}"

  [[items.form.fields]]
  name = "environment"
  label = "Target Environment"
  type = "select"
  options = ["staging", "production"]

  [[items.form.fields]]
  name = "version" 
  label = "Version Tag"
  placeholder = "v1.0.0"
  ```

  ```json dx.json theme={null}
  {
    "items": [
      {
        "name": "Deploy Application",
        "description": "Deploy to specified environment",
        "form": {
          "title": "Application Deployment",
          "fields": [
            {
              "name": "environment",
              "label": "Target Environment",
              "type": "select",
              "options": ["staging", "production"]
            },
            {
              "name": "version",
              "label": "Version Tag",
              "placeholder": "v1.0.0"
            }
          ],
          "submit": "deploy.sh {environment} {version}"
        }
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  Menu configurations support environment variable expansion and can reference relative file paths for maximum flexibility.
</Note>