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

# rest

> cpln rest — Submit raw REST requests directly against the Control Plane API.

Submit REST requests against the API

```none theme={null}
cpln rest [SUBCOMMAND]
```

```text theme={null}
Commands:
  cpln rest create <path>  Submit a POST request followed by a GET request against the referenced path
  cpln rest delete <path>  Submit a DELETE request against the referenced path
  cpln rest edit <path>    Launches the default editor with the contents of the referenced path
  cpln rest get <path>     Submit a GET request against the referenced path
  cpln rest patch <path>   Submit a PATCH request against the referenced path
  cpln rest post <path>    Submit a POST request against the referenced path
  cpln rest put <path>     Submit a PUT request against the referenced path

Context options:
  --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable

Format options:
  --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
  --color       Colorize the output  [boolean] [default: true]
  --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
  --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

Request options:
  --token         Override the authorization token
  --endpoint      Override the API URL
  --insecure, -k  Ignore TLS errors  [boolean]

Debug options:
  --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
  --debug, -d    Show all HTTP communications  [boolean] [default: false]

Options:
  --help  Show help  [boolean]
```

***

#### rest create

Submit a POST request followed by a GET request against the referenced path

**Usage**

```none theme={null}
cpln rest create <path> --file FILE_NAME [OPTIONS]
```

<Note>
  If using the option **--file -**, press Control-D (or Control-Z if you are using Windows) to submit the request
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    path  Resource path (e.g., /org/test/user/adam)  [required]

  Command options:
    --file, -f    File to load the request from. Use `--file -` to enable input from stdin.
    --header, -H  HTTP headers in curl format: "x-header: value"

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln rest create /org --file create-org.json
    ```

    ```text Output theme={null}
    The metadata contained within the JSON file will be performed against the referenced path as a POST request.

    If successful, a GET request will be performed on the resource and outputted to stdout.
    ```
  </CodeGroup>
</Accordion>

***

#### rest delete

Submit a DELETE request against the referenced path

**Usage**

```none theme={null}
cpln rest delete <path> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    path  Resource path (e.g., /org/test/user/adam)  [required]

  Command options:
    --header, -H  HTTP headers in curl format: "x-header: value"

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln rest delete /org/demo-cpln-organization/gvc/demo-gvc
    ```

    ```text Output theme={null}
    The GVC with the reference \`/org/demo-cpln-organization/gvc/demo-gvc\` will be deleted.
    ```
  </CodeGroup>
</Accordion>

***

#### rest edit

Launches the default editor with the contents of the referenced path

**Usage**

```none theme={null}
cpln rest edit <path> [OPTIONS]
```

<Note>
  The default editor can be set by using the EDITOR environment variable.
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    path  Resource path (e.g., /org/test/user/adam)  [required]

  Command options:
    --header, -H  HTTP headers in curl format: "x-header: value"

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln rest edit /org/demo-cpln-organization
    ```

    ```text Output theme={null}
    Your default editor will be launched. 

    Once any modifications are saved, the updates will be sent to the API as a PATCH request.
    ```
  </CodeGroup>
</Accordion>

***

#### rest get

Submit a GET request against the referenced path

**Usage**

```none theme={null}
cpln rest get <path> [OPTIONS]
```

<Note>
  An empty reference will return all references
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    path  Resource path (e.g., /org/test/user/adam)  [required]

  Command options:
    --header, -H  HTTP headers in curl format: "x-header: value"

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln rest get /org/demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------------------+------------------+----------------------------+----------------------+
    |NAME                   |DESCRIPTION       |LINK                        |TAGS                  |
    |-----------------------|------------------|----------------------------|----------------------|
    |demo-cpln-organization |Demo Organization |/org/demo-cpln-organization |demo-key="demo-value" |
    |                       |                  |                            |type="demo"           |
    +-----------------------+------------------+----------------------------+----------------------+
    ```
  </CodeGroup>
</Accordion>

***

#### rest patch

Submit a PATCH request against the referenced path

**Usage**

```none theme={null}
cpln rest patch <path> --file FILE_NAME [OPTIONS]
```

<Note>
  If using the option **--file -**, press Control-D (or Control-Z if you are using Windows) to submit the request
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    path  Resource path (e.g., /org/test/user/adam)  [required]

  Command options:
    --file, -f    File to load the request from. Use `--file -` to enable input from stdin.
    --header, -H  HTTP headers in curl format: "x-header: value"

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln rest patch /org/demo-cpln-organization --file update-org.json
    ```

    ```text Output theme={null}
    The metadata contained within the JSON file will be performed against the referenced path as a PATCH request.
    ```
  </CodeGroup>
</Accordion>

***

#### rest post

Submit a POST request against the referenced path

**Usage**

```none theme={null}
cpln rest post <path> --file FILE_NAME [OPTIONS]
```

<Note>
  If using the option **--file -**, press Control-D (or Control-Z if you are using Windows) to submit the request
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    path  Resource path (e.g., /org/test/user/adam)  [required]

  Command options:
    --file, -f    File to load the request from. Use `--file -` to enable input from stdin.
    --header, -H  HTTP headers in curl format: "x-header: value"

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln rest post /org --file new-org.json
    ```

    ```text Output theme={null}
    The metadata contained within the JSON file will be performed against the referenced path as a POST request.
    ```
  </CodeGroup>
</Accordion>

***

#### rest put

Submit a PUT request against the referenced path

**Usage**

```none theme={null}
cpln rest put <path> [OPTIONS]
```

<Note>
  If using the option **--file -**, press Control-D (or Control-Z if you are using Windows) to submit the request
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    path  Resource path (e.g., /org/test/user/adam)  [required]

  Command options:
    --file, -f    File to load the request from. Use `--file -` to enable input from stdin.
    --header, -H  HTTP headers in curl format: "x-header: value"

  Context options:
    --profile  Override the profile. The default profile can be set using the `cpln profile set-default` command or by setting the CPLN_PROFILE environment variable

  Format options:
    --output, -o  Set the output format  [choices: "text", "json", "yaml", "json-slim", "yaml-slim", "tf", "crd", "names"]
    --color       Colorize the output  [boolean] [default: true]
    --ts          Timestamp format if the output format is text (e.g., --output=text)  [choices: "iso", "local", "age"]
    --max         Maximum number of records to show. A value less than 1 will return all records.  [number] [default: 50]

  Request options:
    --token         Override the authorization token
    --endpoint      Override the API URL
    --insecure, -k  Ignore TLS errors  [boolean]

  Debug options:
    --verbose, -v  Enable verbose output to stderr  [boolean] [default: false]
    --debug, -d    Show all HTTP communications  [boolean] [default: false]

  Options:
    --help  Show help  [boolean]
  ```

  [Common Options Reference](/cli-reference/using-cli/common-options)
</Accordion>

<Accordion title="Example">
  <CodeGroup>
    ```bash Command theme={null}
    cpln rest put /org/demo-cpln-organization --file update-org.json
    ```

    ```text Output theme={null}
    The metadata contained within the JSON file will be performed against the referenced path as a PUT request.
    ```
  </CodeGroup>
</Accordion>

***