### Start Kusion Developer Portal locally

Source: https://github.com/kusionstack/kusion/blob/main/ui/README.md

Install project dependencies and launch the development server.

```shell
npm install
npm start
```

--------------------------------

### Kusion ls command examples

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_ls.md

Various examples of listing project and stack information with different formatting and depth options.

```bash
  # List all project and stack information in the current directory
  kusion ls
  
  # List all project and stack information in the specify directory
  kusion ls ./path/to/project_dir
  
  # List all project and stack information in the specify directory,
  # and output in a Tree format
  kusion ls ./path/to/project_dir --format=tree
  
  # List all project and stack information in the specify directory,
  # and output in a JSON format
  kusion ls ./path/to/project_dir --format=json
  
  # List all project and stack information in the specify directory,
  # and output in a YAML format
  kusion ls ./path/to/project_dir --format=yaml
  
  # List all project and stack by level, and output in a Tree format
  kusion ls ./path/to/project_dir --format=tree --level=1
```

--------------------------------

### Instantiate AppConfiguration

Source: https://github.com/kusionstack/kusion/blob/main/docs/design/collaboration/collaboration_paradigm.md

Example of an application configuration file (main.k) defining workload and database requirements.

```python
wordpress: ac.AppConfiguration {
    workload: wl.Service {
        containers: {
            wordpress: c.Container {
                image = "wordpress:4.8-apache"
                env: {
                    "WORDPRESS_DB_HOST": "$database.hostname"
                    "WORDPRESS_DB_PASSWORD": "$database.password"
                }
                resources: {
                    "cpu": "500m"
                    "memory": "512Mi"
                }
            }
        }
        replicas: 1
        ports: [
            n.Port {
                port: 80
            }
        ]
    }
    database: db.Database {
        engine: "MySQL"
        version: "5.7"
    }
}
```

--------------------------------

### Installing translation tools

Source: https://github.com/kusionstack/kusion/blob/main/pkg/util/i18n/translations/README.md

Install the necessary command-line utilities for extracting strings and merging translation files.

```console
# install go-xgettext
go install github.com/gosexy/gettext/go-xgettext

# install gettext to use msgmerge
brew install gettext
```

--------------------------------

### Example Kusion Module Directory Structure

Source: https://github.com/kusionstack/kusion/blob/main/docs/design/kusion_module/kusion_modules.md

Illustrates the standard file and directory structure for a Kusion module package. Includes essential components like schema definition, binary, configuration files, and example directories.

```shell
$ tree example-module/
.
├── schema.k
├── kusion-module-name_0.1.0 # binary
├── kcl.mod
├── README.md
├── LICENSE
├── example
│ ├── dev
│ │ ├── example.k
│ │ ├── kcl.mod
| | ├── workspace.yaml
│ │ └── stack.yaml
│ └── project.yaml

```

--------------------------------

### Kusion build usage examples

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/zh_CN/kusion_build.md

Common patterns for building Kusion modules with arguments, specific directories, and output configurations.

```bash
  # Build main.k with arguments
  kusion build -D name=test -D age=18
  
  # Build main.k with work directory
  kusion build -w appops/demo/dev
  
  # Build main.k and write result into output.yaml
  kusion build -o output.yaml
  
  # Build without output style and color
  kusion build --no-style=true
```

--------------------------------

### Build Kusion Developer Portal

Source: https://github.com/kusionstack/kusion/blob/main/ui/README.md

Install project dependencies and generate a production build.

```shell
npm install
npm run build
```

--------------------------------

### Get Internal Templates

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_init_templates.md

Use this command to get the name and description of internal templates for project initialization.

```bash
kusion init templates
```

--------------------------------

### Install Kusion CLI with Powershell

Source: https://github.com/kusionstack/kusion/blob/main/README.md

Installs the latest version of the Kusion CLI on Windows using Powershell. This script downloads and executes the installation commands.

```powershell
# install Kusion latest version
powershell -Command "iwr -useb https://www.kusionstack.io/scripts/install.ps1 | iex"
```

--------------------------------

### List Projects and Stacks

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/zh_CN/kusion_ls.md

Use this command to list all project and stack information in the current directory. No special setup is required.

```bash
kusion ls
```

--------------------------------

### Install Kusion CLI with Homebrew

Source: https://github.com/kusionstack/kusion/blob/main/README.md

Installs the Kusion CLI on macOS and Linux using the Homebrew package manager. Ensure you have Homebrew installed first.

```shell
# tap formula repository Kusionstack/tap
brew tap KusionStack/tap

# install Kusion 
brew install KusionStack/tap/kusion
```

--------------------------------

### GET /api/v1/backends

Source: https://context7.com/kusionstack/kusion/llms.txt

List all configured backends.

```APIDOC
## GET /api/v1/backends

### Description
Retrieve a list of all backends.

### Method
GET

### Endpoint
/api/v1/backends

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number
- **pageSize** (integer) - Optional - Number of items per page
```

--------------------------------

### Print Kusion Version

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_version.md

Use this command to display the Kusion version information for the current context. No setup is required.

```bash
kusion version
```

--------------------------------

### AppConfiguration with Built-in and Customized Modules

Source: https://github.com/kusionstack/kusion/blob/main/docs/design/kusion_module/kusion_modules.md

Example of an AppConfiguration defining a workload and accessories, including built-in database and monitoring modules, as well as a customized module. Ensure necessary imports are present.

```python
import kam.v1 as ac
import kam.v1.workload as wl
import kam.v1.workload.container as c
import kam.v1.workload.container.probe as p
import monitoring as m
import database as d

# Note: AppConfiguration per se is not a Kusion Module
  helloWorld: ac.AppConfiguration {
      # Built-in module
      workload: wl.Service {
          containers: {
              "main": c.Container {
                  image: "ghcr.io/kusion-stack/samples/helloworld:latest"
                  # Configure a HTTP readiness probe
                  readinessProbe: p.Probe {
                      probeHandler: p.Http {
                          url: "http://localhost:80"
                      }
                  }
              }
          }
      }

      # a collection of accessories that will be attached to the workload
      accessories: {
       # Built-in module
         "my-database" : d.MySQL {
          type: "cloud"
          version: "8.0"
         }
         # Built-in module
         "my-prometheus" : m.Prometheus {
          path: "/metrics"
         }
         # Customized module
         "my-customize": customizedModule {
           ...
         }
      }
  }
```

--------------------------------

### Delete Workspace Example

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_workspace_delete.md

Example of deleting a specific workspace named dev.

```bash
  # Delete a workspace
  kusion workspace delete dev
```

--------------------------------

### Setup Kubernetes Cluster with K3d

Source: https://github.com/kusionstack/kusion/blob/main/docs/design/E2E Test/E2E Test.md

This Go code snippet demonstrates how to create a K3s Kubernetes cluster using k3d before running tests. It expects the 'k3d cluster create' command to succeed.

```go
var _ = ginkgo.BeforeSuite(func() {
	cli := "k3d cluster create kusion-e2e"
	output, err := Exec(cli)
	gomega.Expect(err).ShouldNot(gomega.HaveOccurred())
	gomega.Expect(output).To(gomega.ContainSubstring("successfully"))
})
```

--------------------------------

### Get Specific Resource

Source: https://context7.com/kusionstack/kusion/llms.txt

Fetches details for a single resource identified by its ID.

```bash
curl -X GET "http://localhost:8080/api/v1/resources/1"
```

--------------------------------

### Get Specific Backend

Source: https://context7.com/kusionstack/kusion/llms.txt

Fetches details for a single backend identified by its ID.

```bash
curl -X GET "http://localhost:8080/api/v1/backends/1"
```

--------------------------------

### Get Templates from Online Repository

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_init_templates.md

Fetch templates from a specific online repository by providing the repository URL and setting the --online flag to true. Ensure the repository URL is correctly formatted.

```bash
kusion init templates https://github.com/<user>/<repo> --online=true
```

--------------------------------

### Kusion Configuration Commands Test Case

Source: https://github.com/kusionstack/kusion/blob/main/docs/design/E2E Test/E2E Test.md

This Go code defines a Ginkgo test suite for Kusion configuration commands. It includes setup to initialize a project and cleanup to remove test artifacts. The test case specifically checks the 'kusion compile' command.

```go
var _ = ginkgo.Describe("Kusion Configuration Commands", func() {
	ginkgo.BeforeEach(func() {
		ginkgo.By("kusion init code-city", func() {
			path := filepath.Join(GetWorkDir(), "testdata")
			output, err := ExecWithWorkDir("kusion init --online=true --yes=true", path)
			gomega.Expect(err).ShouldNot(gomega.HaveOccurred())
			gomega.Expect(output).To(gomega.ContainSubstring("Created project"))
		})
	})

	ginkgo.AfterEach(func() {
		ginkgo.By("clean up code-city", func() {
			path := filepath.Join(GetWorkDir(), "testdata", "code-city")
			cli := fmt.Sprintf("rm -rf %s", path)
			output, err := Exec(cli)
			gomega.Expect(err).ShouldNot(gomega.HaveOccurred())
			gomega.Expect(output).To(gomega.BeEmpty())
		})
	})

	ginkgo.Context("kusion compile testing", func() {
		ginkgo.It("kusion compile", func() {
			// kusion compile testing
			path := filepath.Join(GetWorkDir(), "testdata", "code-city", "dev")
			output, err := ExecWithWorkDir("kusion compile", path)
			gomega.Expect(err).ShouldNot(gomega.HaveOccurred())
			gomega.Expect(output).To(gomega.BeEmpty())
		})
	})
})
```

--------------------------------

### AWS Proton Service Specification Example

Source: https://github.com/kusionstack/kusion/blob/main/docs/design/collaboration/collaboration_paradigm.md

This YAML file defines the specification for a service in AWS Proton, including pipeline configurations and instance details like desired count, port, and task size.

```yaml
proton: ServiceSpec

pipeline:
  unit_test_command: "ls"

instances:
  - name: "frontend-dev"
    environment: "Beta"
    spec:
      desired_count: 2
      port: 80
      task_size: "medium"
```

--------------------------------

### Initialize Project with Internal Templates

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_init.md

Use this command to initialize a new project using the default internal templates provided by Kusion. No additional arguments are required.

```bash
kusion init
```

--------------------------------

### Initialize Project with Online Templates

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_init.md

Initialize a project using templates from an online repository. Set `--online=true` to fetch templates from the web. This command uses default online templates.

```bash
kusion init --online=true
```

--------------------------------

### Initialize Project with Specific Online Template

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_init.md

Initialize a project from a specific online template repository. Provide the URL to the GitHub repository and set `--online=true`.

```bash
kusion init https://github.com/<user>/<repo> --online=true
```

--------------------------------

### Initialize Project with Default Values

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_init.md

Skip all interactive prompts and proceed with initialization using default values by using the `--yes` flag. This is useful for automation.

```bash
kusion init --yes
```

--------------------------------

### Initialize Project with Specified Name and Template

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_init.md

Initialize a project with a predefined project name and template name. Use `--project-name` and `--template-name` to avoid interactive prompts for these values.

```bash
kusion init --project-name my-app --template-name web-app
```

--------------------------------

### Create Local Backend

Source: https://context7.com/kusionstack/kusion/llms.txt

Creates a new backend configuration for local filesystem storage. Requires name, description, and backendConfig with type 'local' and path.

```bash
curl -X POST "http://localhost:8080/api/v1/backends" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "local-backend",
    "description": "Local filesystem backend",
    "backendConfig": {
      "type": "local",
      "configs": {
        "path": "/var/kusion/state"
      }
    }
  }'
```

--------------------------------

### GET /api/v1/variablesets

Source: https://context7.com/kusionstack/kusion/llms.txt

Lists all available variable sets.

```APIDOC
## GET /api/v1/variablesets

### Description
Lists all variable sets.

### Method
GET

### Endpoint
/api/v1/variablesets
```

--------------------------------

### GET /api/v1/resources

Source: https://context7.com/kusionstack/kusion/llms.txt

List and query deployed resources.

```APIDOC
## GET /api/v1/resources

### Description
List all resources or filter by type and plane.

### Method
GET

### Endpoint
/api/v1/resources

### Parameters
#### Query Parameters
- **stackID** (integer) - Optional - Filter by stack ID
- **page** (integer) - Optional - Page number
- **pageSize** (integer) - Optional - Items per page
- **resourceType** (string) - Optional - Filter by resource type
- **resourcePlane** (string) - Optional - Filter by resource plane
```

--------------------------------

### List All Sources

Source: https://context7.com/kusionstack/kusion/llms.txt

Retrieves a list of all configured configuration sources.

```bash
curl -X GET "http://localhost:8080/api/v1/sources"
```

--------------------------------

### Initialize Project with Custom Parameters

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_init.md

Initialize a project and provide custom parameters in JSON format using the `--custom-params` flag. These parameters will override default template values and skip interactive prompts.

```bash
kusion init --custom-params '{"key": "value"}'
```

--------------------------------

### GET /api/v1/runs

Source: https://context7.com/kusionstack/kusion/llms.txt

List and filter execution runs.

```APIDOC
## GET /api/v1/runs

### Description
List all runs with optional filtering by stack, status, type, or date range.

### Method
GET

### Endpoint
/api/v1/runs

### Parameters
#### Query Parameters
- **stackID** (integer) - Optional - Filter by stack ID
- **status** (string) - Optional - Filter by status
- **type** (string) - Optional - Filter by run type
- **startTime** (string) - Optional - Start of date range
- **endTime** (string) - Optional - End of date range
```

--------------------------------

### Initialize Project with Specific Local Template

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_init.md

Initialize a project using a local template directory. Specify the path to the template directory on your local filesystem.

```bash
kusion init /path/to/templates
```

--------------------------------

### GET /api/v1/variables/{variableSet}/{name}

Source: https://context7.com/kusionstack/kusion/llms.txt

Retrieves the details of a specific variable.

```APIDOC
## GET /api/v1/variables/{variableSet}/{name}

### Description
Retrieves a specific variable by its set and name.

### Method
GET

### Endpoint
/api/v1/variables/{variableSet}/{name}

### Parameters
#### Path Parameters
- **variableSet** (string) - Required - The variable set name
- **name** (string) - Required - The variable name
```

--------------------------------

### Run kusion preview with a specified intent file

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_preview.md

Use the --intent-file flag to specify the path to the intent file. The file must be in the working directory or its subdirectories.

```bash
kusion preview --intent-file intent.yaml
```

--------------------------------

### Delete current stack resources

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_destroy.md

Example usage for deleting resources in the current stack.

```bash
  # Delete resources of current stack
  kusion destroy
```

--------------------------------

### Get Run Result

Source: https://context7.com/kusionstack/kusion/llms.txt

Retrieves the result of a specific execution run identified by its ID.

```bash
curl -X GET "http://localhost:8080/api/v1/runs/1/result"
```

--------------------------------

### Initialize Project Scaffolding with kusion init

Source: https://context7.com/kusionstack/kusion/llms.txt

Creates a new project structure using built-in or custom templates. Templates can be sourced from local paths or remote repositories.

```bash
# Initialize a project from internal templates (interactive)
kusion init

# Initialize with a specific template name
kusion init --template-name quickstart --project-name my-app

# Initialize from online templates
kusion init --online=true

# Initialize from a specific GitHub repository
kusion init https://github.com/KusionStack/kusion-templates --online=true

# Initialize from a local template directory
kusion init /path/to/templates

# Initialize with custom parameters (skip prompts)
kusion init --custom-params '{"name":"myapp","replicas":3}' --yes

# Force overwrite existing files
kusion init --force --project-name my-app
```

--------------------------------

### Get Specific Run

Source: https://context7.com/kusionstack/kusion/llms.txt

Fetches details for a single execution run identified by its ID.

```bash
curl -X GET "http://localhost:8080/api/v1/runs/1"
```

--------------------------------

### Create Module

Source: https://context7.com/kusionstack/kusion/llms.txt

Creates a new Kusion module. Requires name, URL, description, doc link, and owners.

```bash
curl -X POST "http://localhost:8080/api/v1/modules" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "redis",
    "url": "oci://ghcr.io/kusionstack/redis",
    "description": "Redis cache module",
    "doc": "https://kusionstack.io/docs/modules/redis",
    "owners": ["platform-team"]
  }'
```

--------------------------------

### Kusion build command options

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/zh_CN/kusion_build.md

Available flags for configuring the build process.

```text
  -D, --argument stringToString   指定顶级参数 (default [])
  -h, --help                      help for build
      --no-style                  禁用输出的样式与颜色
  -o, --output string             指定输出文件
  -w, --workdir string            指定工作目录
```

--------------------------------

### Get Specific Module

Source: https://context7.com/kusionstack/kusion/llms.txt

Fetches details for a specific module identified by its name (e.g., 'mysql').

```bash
curl -X GET "http://localhost:8080/api/v1/modules/mysql"
```

--------------------------------

### List Projects and Stacks in JSON Format

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/zh_CN/kusion_ls.md

Obtain project and stack information in JSON format for programmatic use. Use the --format=json flag.

```bash
kusion ls ./path/to/project_dir --format=json
```

--------------------------------

### Get Resource Graph

Source: https://context7.com/kusionstack/kusion/llms.txt

Retrieves the resource graph for a specific stack ID, visualizing resource relationships.

```bash
curl -X GET "http://localhost:8080/api/v1/resources/graph?stackID=1"
```

--------------------------------

### POST /kusion/workspace/create

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_workspace_create.md

Creates a new workspace with a specified name and configuration file.

```APIDOC
## POST /kusion/workspace/create

### Description
Creates a new workspace with a specified name and configuration file. The configuration file must be in YAML format.

### Method
POST

### Endpoint
/kusion/workspace/create

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the workspace to create.
- **-f, --file** (string) - Required - The path to the workspace configuration file (YAML format).

### Request Example
```json
{
  "name": "dev",
  "file": "dev.yaml"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the workspace was created successfully.

#### Response Example
```json
{
  "message": "Workspace 'dev' created successfully."
}
```

### Error Handling
- **400 Bad Request**: If the configuration file is missing or not in YAML format.
- **409 Conflict**: If a workspace with the same name already exists.
```

--------------------------------

### Get Workspace Configurations - REST API

Source: https://context7.com/kusionstack/kusion/llms.txt

Retrieve the configuration details for a specific workspace using its ID.

```bash
curl -X GET "http://localhost:8080/api/v1/workspaces/1/configs"
```

--------------------------------

### Get Specific Workspace by ID - REST API

Source: https://context7.com/kusionstack/kusion/llms.txt

Fetch details for a single workspace using its unique identifier.

```bash
curl -X GET "http://localhost:8080/api/v1/workspaces/1"
```

--------------------------------

### Get Specific Stack by ID - REST API

Source: https://context7.com/kusionstack/kusion/llms.txt

Fetch details for a single stack using its unique identifier.

```bash
curl -X GET "http://localhost:8080/api/v1/stacks/1"
```

--------------------------------

### Build Kusion Configurations with Settings File

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_build.md

Builds Kusion configurations, loading arguments and settings from a specified YAML file using the -Y flag.

```bash
kusion build -Y settings.yaml
```

--------------------------------

### Force Project Initialization

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_init.md

Force the generation of scaffolding files, overwriting existing files if necessary. Use the `--force` flag when you need to ensure the latest scaffolding is applied.

```bash
kusion init --force
```

--------------------------------

### Get Specific Project by ID - REST API

Source: https://context7.com/kusionstack/kusion/llms.txt

Fetch details for a single project using its unique identifier.

```bash
curl -X GET "http://localhost:8080/api/v1/projects/1" \
  -H "Content-Type: application/json"
```

--------------------------------

### List Runs by Date Range

Source: https://context7.com/kusionstack/kusion/llms.txt

Retrieves a list of execution runs filtered by a specified start and end time.

```bash
curl -X GET "http://localhost:8080/api/v1/runs?startTime=2024-01-01T00:00:00Z&endTime=2024-12-31T23:59:59Z"
```

--------------------------------

### Run kusion preview with specified arguments

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_preview.md

Use the -D flag to specify top-level arguments for the preview. Multiple arguments can be provided.

```bash
kusion preview -D name=test -D age=18
```

--------------------------------

### List Projects and Stacks in YAML Format

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/zh_CN/kusion_ls.md

Retrieve project and stack details in YAML format. This is useful for configuration or integration purposes. Use the --format=yaml flag.

```bash
kusion ls ./path/to/project_dir --format=yaml
```

--------------------------------

### Print Kusion Environment Information as JSON

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_env.md

Use the --json flag to get Kusion environment information in JSON format. This is useful for programmatic parsing.

```bash
kusion env --json
```

--------------------------------

### Create OCI Source

Source: https://context7.com/kusionstack/kusion/llms.txt

Creates a new configuration source using an OCI registry. Requires name, remote URL, and source provider 'oci'.

```bash
curl -X POST "http://localhost:8080/api/v1/sources" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "oci-registry",
    "remote": "oci://ghcr.io/myorg/configs",
    "sourceProvider": "oci"
  }'
```

--------------------------------

### Create OSS Backend

Source: https://context7.com/kusionstack/kusion/llms.txt

Creates a new backend configuration for Alibaba Cloud OSS storage. Requires name and backendConfig with type 'oss', including endpoint, bucket, and prefix.

```bash
curl -X POST "http://localhost:8080/api/v1/backends" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "oss-backend",
    "backendConfig": {
      "type": "oss",
      "configs": {
        "endpoint": "oss-cn-hangzhou.aliyuncs.com",
        "bucket": "my-kusion-bucket",
        "prefix": "state"
      }
    }
  }'
```

--------------------------------

### kusion workspace create command synopsis

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_workspace_create.md

This is the basic syntax for creating a workspace. The '-f' flag specifies the configuration file.

```bash
kusion workspace create
```

--------------------------------

### Run kusion preview with a specified work directory

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_preview.md

Use the -w flag to specify the working directory for the preview operation.

```bash
kusion preview -w /path/to/workdir
```

--------------------------------

### Build Kusion Configurations to Output File

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_build.md

Builds Kusion configurations and writes the results to a specified output file using the -o flag.

```bash
kusion build -o output.yaml
```

--------------------------------

### Create Git Source

Source: https://context7.com/kusionstack/kusion/llms.txt

Creates a new configuration source using a Git repository. Requires name, remote URL, source provider, description, and owners.

```bash
curl -X POST "http://localhost:8080/api/v1/sources" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "main-repo",
    "remote": "https://github.com/myorg/infrastructure",
    "sourceProvider": "github",
    "description": "Main infrastructure repository",
    "owners": ["platform-team"]
  }'
```

--------------------------------

### Manage Workspaces with kusion workspace

Source: https://context7.com/kusionstack/kusion/llms.txt

Lists deployment targets containing platform-level configurations.

```bash
# List all workspaces
kusion workspace list
```

--------------------------------

### List Projects and Stacks by Level in Tree Format

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/zh_CN/kusion_ls.md

Display project and stack information in a tree format, limited to a specific level of depth. Use the --format=tree and --level flags.

```bash
kusion ls ./path/to/project_dir --format=tree --level=1
```

--------------------------------

### List All Backends

Source: https://context7.com/kusionstack/kusion/llms.txt

Retrieves a paginated list of all configured backends. Specify page and pageSize for pagination.

```bash
curl -X GET "http://localhost:8080/api/v1/backends?page=1&pageSize=10"
```

--------------------------------

### Run kusion preview without output styling

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_preview.md

Use the --no-style=true flag to disable all styling and use raw output mode.

```bash
kusion preview --no-style=true
```

--------------------------------

### List Projects and Stacks in Specific Directory

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/zh_CN/kusion_ls.md

Specify a directory to list project and stack information from that location. Ensure the path is correct.

```bash
kusion ls ./path/to/project_dir
```

--------------------------------

### Workspace list command options

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_workspace_list.md

Displays help information for the list command.

```bash
  -h, --help   help for list
```

--------------------------------

### Kusion Build Command Synopsis

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_build.md

The basic syntax for the kusion build command.

```bash
kusion build [flags]
```

--------------------------------

### Run kusion preview with JSON output format

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_preview.md

Use the -o json flag to specify the output format as JSON.

```bash
kusion preview -o json
```

--------------------------------

### Workspace command help options

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_workspace.md

Displays help information for the workspace command.

```bash
  -h, --help   help for workspace
```

--------------------------------

### POST /api/v1/sources

Source: https://context7.com/kusionstack/kusion/llms.txt

Create a new configuration source.

```APIDOC
## POST /api/v1/sources

### Description
Register a new Git or OCI configuration source.

### Method
POST

### Endpoint
/api/v1/sources

### Request Body
- **name** (string) - Required - Source name
- **remote** (string) - Required - Remote repository URL
- **sourceProvider** (string) - Required - Provider type (github, oci)
- **description** (string) - Optional - Description
- **owners** (array) - Optional - List of owners
```

--------------------------------

### Manage Kusion Workspaces via CLI

Source: https://context7.com/kusionstack/kusion/llms.txt

Use these CLI commands to create, view, update, and delete Kusion workspaces. Ensure you have the correct configuration files for creation and updates.

```bash
kusion workspace create dev -f dev.yaml
```

```bash
kusion workspace show dev
```

```bash
kusion workspace update dev -f dev-updated.yaml
```

```bash
kusion workspace delete staging
```

--------------------------------

### List All Modules

Source: https://context7.com/kusionstack/kusion/llms.txt

Retrieves a paginated list of all available Kusion modules.

```bash
curl -X GET "http://localhost:8080/api/v1/modules?page=1&pageSize=10"
```

--------------------------------

### List Projects and Stacks in Tree Format

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/zh_CN/kusion_ls.md

Output project and stack information in a tree format for better visualization of hierarchy. Requires specifying the directory and the --format=tree flag.

```bash
kusion ls ./path/to/project_dir --format=tree
```

--------------------------------

### POST /api/v1/backends

Source: https://context7.com/kusionstack/kusion/llms.txt

Create a new backend configuration.

```APIDOC
## POST /api/v1/backends

### Description
Create a new backend (local, S3, or OSS).

### Method
POST

### Endpoint
/api/v1/backends

### Request Body
- **name** (string) - Required - Name of the backend
- **description** (string) - Optional - Description of the backend
- **backendConfig** (object) - Required - Configuration details for the specific backend type
```

--------------------------------

### Kusion Build Command Options

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_build.md

Available flags for the kusion build command, including argument specification, help, output file, settings files, and work directory.

```bash
-D, --argument stringToString   Specify the top-level argument (default [])
-h, --help                      help for build
    --no-style                  Disable the output style and color
-o, --output string             Specify the output file
-Y, --setting strings           Specify the command line setting files
-w, --workdir string            Specify the work directory
```

--------------------------------

### Create New Project - REST API

Source: https://context7.com/kusionstack/kusion/llms.txt

Create a new project by sending a POST request with project details in the JSON body. Ensure all required fields like name, path, and IDs are provided.

```bash
curl -X POST "http://localhost:8080/api/v1/projects" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "path": "apps/my-app",
    "description": "My application project",
    "sourceID": 1,
    "organizationID": 1,
    "owners": ["platform-team"],
    "labels": ["production", "web"]
  }'
```

--------------------------------

### Apply with Specified Intent File

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_apply.md

Apply resources defined in a specific intent file. The file must be in the working directory or its subdirectories.

```bash
kusion apply --intent-file intent.yaml
```

--------------------------------

### Create a new workspace

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_workspace_create.md

Use this command to create a new workspace, specifying its name and the path to its configuration file. The configuration file must be in YAML format.

```bash
kusion workspace create dev -f dev.yaml
```

--------------------------------

### List All Resources

Source: https://context7.com/kusionstack/kusion/llms.txt

Retrieves a paginated list of all deployed resources, filterable by stack ID.

```bash
curl -X GET "http://localhost:8080/api/v1/resources?stackID=1&page=1&pageSize=20"
```

--------------------------------

### Apply with Automatic Approval

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_apply.md

Use the --yes flag to skip the interactive approval step and automatically proceed with applying the changes after preview.

```bash
kusion apply --yes
```

--------------------------------

### POST /api/v1/modules

Source: https://context7.com/kusionstack/kusion/llms.txt

Create a new infrastructure module.

```APIDOC
## POST /api/v1/modules

### Description
Register a new reusable infrastructure module.

### Method
POST

### Endpoint
/api/v1/modules

### Request Body
- **name** (string) - Required - Module name
- **url** (string) - Required - Module source URL
- **description** (string) - Optional - Module description
- **doc** (string) - Optional - Documentation URL
- **owners** (array) - Optional - List of owners
```

--------------------------------

### List all workspace names

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_workspace_list.md

Executes the command to display all workspace names.

```bash
kusion workspace list
```

```bash
  # List all workspace names
  kusion workspace list
```

--------------------------------

### Kusion Version Command Options

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_version.md

Available options for the 'kusion version' command, including help and output format.

```bash
-h, --help            help for version
-o, --output string   Output format. Only json format is supported for now
```

--------------------------------

### Kusion CLI Options

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion.md

Global flags available for Kusion commands, including help and profiling configurations.

```bash
  -h, --help                    help for kusion
      --profile string          Name of profile to capture. One of (none|cpu|heap|goroutine|threadcreate|block|mutex) (default "none")
      --profile-output string   Name of the file to write the profile to (default "profile.pprof")
```

--------------------------------

### Configure Workspace Settings

Source: https://context7.com/kusionstack/kusion/llms.txt

Define platform-level modules, secret store providers, and context settings in YAML.

```yaml
# Workspace configuration for production environment
modules:
  mysql:
    path: ghcr.io/kusionstack/mysql
    version: 0.1.0
    configs:
      default:
        type: aws
        version: '8.0'
        instanceType: db.t3.medium
      highPerformance:
        projectSelector:
          - critical-app
          - analytics
        instanceType: db.r5.large
  network:
    configs:
      default:
        type: aws
  redis:
    path: ghcr.io/kusionstack/redis
    version: 0.2.0
    configs:
      default:
        type: aws
        nodeType: cache.t3.micro
context:
  kubernetes:
    config: /etc/kubeconfig.yaml
    namespace: production
secretStore:
  provider:
    aws:
      region: us-west-2
    # Alternative providers:
    # vault:
    #   server: https://vault.example.com:8200
    #   path: secret
    #   version: v2
    # azure:
    #   vaultUrl: https://myvault.vault.azure.net
    #   tenantId: your-tenant-id
```

--------------------------------

### Preview Resource Changes with kusion preview

Source: https://context7.com/kusionstack/kusion/llms.txt

Generates an execution preview of resource changes without applying them to the target environment.

```bash
# Preview changes in current stack
kusion preview

# Preview with work directory
kusion preview -w /path/to/workdir

# Preview with arguments
kusion preview -D name=test -D age=18

# Preview with a pre-built intent file
kusion preview --intent-file intent.yaml

# Preview with ignored fields (useful for frequently changing metadata)
kusion preview --ignore-fields="metadata.generation,metadata.managedFields"

# Preview with JSON output format
kusion preview -o json

# Preview showing all details automatically
kusion preview -d -a

# Preview without colors and styling
kusion preview --no-style=true
```

--------------------------------

### Apply without Style and Color

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_apply.md

Disable output styling and color for a raw output experience.

```bash
kusion apply --no-style=true
```

--------------------------------

### Check KCL Configuration with Settings File

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_check.md

Check KCL configurations using arguments defined in a settings file. Specify the settings file with the -Y flag.

```bash
kusion check main.k -Y settings.yaml
```

--------------------------------

### Create S3 Backend

Source: https://context7.com/kusionstack/kusion/llms.txt

Creates a new backend configuration for AWS S3 storage. Requires name, description, and backendConfig with type 's3', including bucket, region, and prefix.

```bash
curl -X POST "http://localhost:8080/api/v1/backends" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "s3-backend",
    "description": "AWS S3 backend",
    "backendConfig": {
      "type": "s3",
      "configs": {
        "bucket": "my-kusion-state",
        "region": "us-west-2",
        "prefix": "kusion/state"
      }
    }
  }'
```

--------------------------------

### Build Kusion Modules with Arguments

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_build.md

Builds Kusion modules, specifying top-level arguments for KCL placeholders. Use -D for each argument.

```bash
kusion build -D name=test -D age=18
```

--------------------------------

### Initialize E2E Test Suite

Source: https://github.com/kusionstack/kusion/blob/main/docs/design/E2E Test/E2E Test.md

This Go code initializes the Ginkgo testing framework and registers a fail handler for the E2E test suite. It should be called once before running tests.

```go
func TestE2e(t *testing.T) {
	gomega.RegisterFailHandler(ginkgo.Fail)
	ginkgo.RunSpecs(t, "E2e Suite")
}
```

--------------------------------

### kusion preview

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_preview.md

Preview a series of resource changes within the stack. This command generates an execution preview for user approval before making any changes to resources.

```APIDOC
## kusion preview

### Description

Preview a series of resource changes within the stack. Create, update or delete resources according to the intent described in the stack. By default, Kusion will generate an execution preview and present it for your approval before taking any action.

### Synopsis

```
kusion preview [flags]
```

### Options

```
  -a, --all --detail              Automatically show all preview details, combined use with flag --detail
  -D, --argument stringToString   Specify the top-level argument (default [])
  -C, --backend-config strings    backend-config config state storage backend
      --backend-type string       backend-type specify state storage backend
  -d, --detail                    Automatically show preview details with interactive options (default true)
  -h, --help                      help for preview
      --ignore-fields strings     Ignore differences of target fields
      --intent-file string        Specify the intent file path as input, and the intent file must be located in the working directory or its subdirectories
      --no-style                  no-style sets to RawOutput mode and disables all of styling
      --operator string           Specify the operator
  -o, --output string             Specify the output format
  -Y, --setting strings           Specify the command line setting files
  -w, --workdir string            Specify the work directory
```

### Examples

```
# Preview with specified work directory
kusion preview -w /path/to/workdir

# Preview with specified arguments
kusion preview -D name=test -D age=18

# Preview with specified intent file
kusion preview --intent-file intent.yaml

# Preview with ignored fields
kusion preview --ignore-fields="metadata.generation,metadata.managedFields"

# Preview with json format result
kusion preview -o json

# Preview without output style and color
kusion preview --no-style=true
```
```

--------------------------------

### Apply with Watch Enabled

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_apply.md

Enable watching for changes after the initial creation, update, or deletion of requested objects.

```bash
kusion apply --watch
```

--------------------------------

### Apply Resource Changes with kusion apply

Source: https://context7.com/kusionstack/kusion/llms.txt

Applies the operational intent to create, update, or delete resources. Supports dry-run modes and interactive approval.

```bash
# Apply with interactive preview (default)
kusion apply

# Apply with specified work directory
kusion apply -w /path/to/workdir

# Apply with arguments
kusion apply -D name=test -D age=18

# Apply with a pre-built intent file
kusion apply --intent-file intent.yaml

# Skip interactive approval
kusion apply --yes

# Apply in dry-run mode (preview only, no changes)
kusion apply --dry-run

# Apply and watch for changes
kusion apply --watch

# Apply with ignored fields
kusion apply --ignore-fields="metadata.generation"

# Apply with all preview details shown automatically
kusion apply -d -a --yes

# Apply without styling
kusion apply --no-style=true
```

--------------------------------

### Print Kusion Environment Information

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_env.md

Use this command to display general Kusion environment details. The output is formatted as a shell script by default.

```bash
kusion env
```

--------------------------------

### Execute kusion workspace command

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_workspace.md

Basic usage of the workspace command to view available options.

```bash
kusion workspace [flags]
```

--------------------------------

### Execute kusion destroy

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_destroy.md

Basic syntax for running the destroy command.

```bash
kusion destroy [flags]
```

--------------------------------

### Check KCL Configuration with Arguments

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_check.md

Check KCL configurations while providing top-level arguments. Arguments are specified using the -D flag.

```bash
kusion check main.k -D name=test -D age=18
```

--------------------------------

### Check KCL Configuration with Work Directory

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_check.md

Check KCL configurations within a specified work directory. Use the -w flag to set the work directory.

```bash
kusion check main.k -w appops/demo/dev
```

--------------------------------

### Parent command options

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_destroy.md

Global options inherited from parent commands.

```text
      --profile string          Name of profile to capture. One of (none|cpu|heap|goroutine|threadcreate|block|mutex) (default "none")
      --profile-output string   Name of the file to write the profile to (default "profile.pprof")
```

--------------------------------

### Build Kusion Modules without Style

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_build.md

Builds Kusion modules while disabling output styling and color using the --no-style flag.

```bash
kusion build --no-style=true
```

--------------------------------

### GitHub Actions CI Workflow for E2E Tests

Source: https://github.com/kusionstack/kusion/blob/main/docs/design/E2E Test/E2E Test.md

This YAML configuration defines a GitHub Actions workflow to automate end-to-end testing. It checks out code, sets up Go and K3d, and runs the 'make e2e-test' command.

```yaml
name: CI Workflow
on:
  push:
    branches:
      - master
      - release-*
    tags:
      - v*
  pull_request:
    branches:
      - master
      - release-*
jobs:
  e2e:
    name: e2e test
    runs-on: ubuntu-20.04
    steps:
      - name: checkout code
        uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: install Go
        uses: actions/setup-go@v2
        with:
          go-version: 1.17
      - name: Setup K3d
        uses: nolar/setup-k3d-k3s@v1.0.8
        with:
          version: v1.20
      - name: run e2e
        run: make e2e-test
```

--------------------------------

### Workspace update command options

Source: https://github.com/kusionstack/kusion/blob/main/docs/cmd/en_US/kusion_workspace_update.md

Lists the available flags for the update command, including the required file path.

```text
  -f, --file string   the path of workspace configuration file
  -h, --help          help for update
```