> ## 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.

# Common Options

> Shared flags and options available across Control Plane CLI commands.

These options are available on most CLI commands and help you control context, output, connectivity, and behavior.

## Context and profiles

Control which profile, organization, and GVC the command uses.

### `--profile`

Override the default profile for a single command.

```bash theme={null}
cpln <command> --profile <profile-name>
```

<Info>
  Set a default profile with `cpln profile set-default <name>` or use the `CPLN_PROFILE` environment variable.
</Info>

### `--org`

Override the default organization.

```bash theme={null}
cpln <command> --org <org-name>
```

<Info>
  Set a default org in your profile with `cpln profile update <name> --org <org-name>`.
</Info>

### `--gvc`

Override the default Global Virtual Cloud.

```bash theme={null}
cpln <command> --gvc <gvc-name>
```

<Info>
  Set a default GVC in your profile with `cpln profile update <name> --gvc <gvc-name>`.
</Info>

## Output and formatting

Control how command results are displayed.

### `--output` or `-o`

Set the output format.

```bash theme={null}
cpln <command> --output <format>
```

Available formats:

* `text` (default) - Human-readable table
* `json` - Full JSON output
* `yaml` - Full YAML output
* `json-slim` - JSON without IDs, versions, timestamps
* `yaml-slim` - YAML without IDs, versions, timestamps
* `tf` - Terraform HCL format
* `crd` - Kubernetes Custom Resource Definition
* `names` - Resource names only

<Tip>
  Use `json-slim` or `yaml-slim` to get clean output suitable for `cpln apply`.
</Tip>

See [Output Formats](/cli-reference/using-cli/output) for details.

### `--color`

Enable or disable colored output.

```bash theme={null}
cpln <command> --color=false
```

* Type: boolean
* Default: `true`
* Automatically disabled when stdout is not a terminal

### `--ts`

Format timestamps in text output.

```bash theme={null}
cpln <command> --ts <format>
```

Available formats:

* `iso` - ISO 8601 format
* `local` - Local timezone
* `age` - Relative time (e.g., "2 hours ago")

<Note>
  Only applies when `--output=text`.
</Note>

### `--max`

Limit the number of records displayed.

```bash theme={null}
cpln <command> --max <number>
```

* Type: number
* Default: `50`
* Values less than 1 return all records

## Request and connectivity

Control API connectivity and authentication.

### `--token`

Override the authentication token for a single command.

```bash theme={null}
cpln <command> --token <token>
```

<Info>
  View your profile's token with `cpln profile token <profile-name>`.
</Info>

### `--endpoint`

Override the API URL.

```bash theme={null}
cpln <command> --endpoint <url>
```

* Default: `https://api.cpln.io/`

<Warning>
  Only change this for testing or if directed by Control Plane support.
</Warning>

### `--insecure` or `-k`

Ignore TLS certificate errors.

```bash theme={null}
cpln <command> --insecure
```

<Warning>
  Use only for debugging TLS issues. Prefer fixing certificate trust configuration.
</Warning>

## Resource creation and updates

Common flags for `create`, `update`, and `patch` commands.

### `--name`

Specify the resource name.

```bash theme={null}
cpln <command> create --name <resource-name>
```

### `--description` or `--desc`

Add a description to the resource.

```bash theme={null}
cpln <command> create --name <name> --description "Resource description"
```

If not provided, defaults to the resource name.

### `--tag`

Add tags to a resource. Tags are key-value pairs used for organization and policy targeting.

```bash theme={null}
cpln <command> create --tag <key>=<value>
```

<CodeGroup>
  ```bash String value theme={null}
  cpln <command> create --tag environment=production
  ```

  ```bash Force string with colon theme={null}
  cpln <command> create --tag id:1234
  ```

  ```bash Multiple tags theme={null}
  cpln <command> create --tag env=prod --tag team=platform
  ```
</CodeGroup>

<Note>
  The `=` syntax auto-detects JSON types (`true` becomes boolean). Use `:` to force string values.
</Note>

### `--file` or `-f`

Provide input from a file.

```bash theme={null}
cpln apply --file <path>
```

Use `--file -` to read from stdin:

```bash theme={null}
cat resource.yaml | cpln apply --file -
```

## Query filters

Filter results in `query` subcommands.

### `--match`

Query match type.

```bash theme={null}
cpln <command> query --match <type>
```

Available types:

* `all` (default) - Match all conditions
* `any` - Match any condition
* `none` - Match none of the conditions

### `--property` or `--prop`

Filter by resource property.

```bash theme={null}
cpln <command> query --property <property>=<value>
```

<CodeGroup>
  ```bash Filter by name theme={null}
  cpln agent query --property name=my-agent
  ```

  ```bash Filter by status theme={null}
  cpln workload query --property status.phase=running
  ```
</CodeGroup>

### `--tag`

Filter by tag.

```bash theme={null}
cpln <command> query --tag <key>=<value>
```

Example:

```bash theme={null}
cpln gvc query --tag environment=production
```

### `--rel`

Filter by resource relation.

```bash theme={null}
cpln workload query --rel gvc=my-gvc
```

## Diagnostics

Debug CLI and API interactions.

### `--verbose` or `-v`

Enable verbose output to stderr.

```bash theme={null}
cpln <command> --verbose
```

Shows additional operational details.

### `--debug` or `-d`

Display all HTTP communications with the API.

```bash theme={null}
cpln <command> --debug
```

<Warning>
  Debug output may include sensitive information. Use with caution.
</Warning>

## Environment variable alternatives

Many flags can be set via environment variables:

| Flag        | Environment Variable |
| ----------- | -------------------- |
| `--profile` | `CPLN_PROFILE`       |
| `--token`   | `CPLN_TOKEN`         |
| `--org`     | `CPLN_ORG`           |
| `--gvc`     | `CPLN_GVC`           |

<CodeGroup>
  ```bash Set via environment theme={null}
  export CPLN_ORG=my-org
  export CPLN_GVC=my-gvc
  cpln workload get
  ```

  ```bash Set via flags theme={null}
  cpln workload get --org my-org --gvc my-gvc
  ```
</CodeGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Output Formats" href="/cli-reference/using-cli/output" icon="code">
    Learn about output format options
  </Card>

  <Card title="Profiles" href="/cli-reference/get-started/profiles" icon="user">
    Configure default contexts
  </Card>
</CardGroup>