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

# agent

> cpln agent — Manage agents that connect self-hosted infrastructure to Control Plane.

Manage agents

For a detailed overview, please visit the [agent's](/reference/agent) reference page.

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

```text theme={null}
Commands:
  cpln agent access-report <ref>  Show the access report for the referenced agent
  cpln agent audit [ref]          Retrieve audit trail events for the referenced agent
  cpln agent create               Create a new agent
  cpln agent delete <ref...>      Delete one or more referenced agents
  cpln agent edit <ref>           Edit the referenced agent, as YAML, within an editor
  cpln agent eventlog <ref>       Show the event log of the referenced agent  [aliases: log]
  cpln agent get [ref...]         Retrieve one or more referenced agents
  cpln agent info <ref>           Get info about an agent
  cpln agent manifest             Generate a manifest for running an agent in K8S
  cpln agent patch <ref>          Update the referenced agent's metadata using an input file
  cpln agent permissions          Show the grantable permissions for an agent object type
  cpln agent query                Find all the agents based on the given query
  cpln agent tag <ref...>         Manage the tags belonging to one or more referenced agents
  cpln agent up                   Run an agent within a local Docker instance
  cpln agent update <ref>         Update properties of the referenced agent

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

***

#### agent access-report

Show the access report for the referenced agent

**Usage**

```none theme={null}
cpln agent access-report <ref> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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 agent access-report demo-agent --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+--------------------------------------------------------+--------+
    |PERMISSION |PRINCIPAL                                               |GRANTED |
    |-----------|--------------------------------------------------------|--------|
    |create     |/org/demo-cpln-organization/group/superusers            |manage  |
    |create     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |delete     |/org/demo-cpln-organization/group/superusers            |manage  |
    |delete     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |edit       |/org/demo-cpln-organization/group/superusers            |manage  |
    |edit       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |manage     |/org/demo-cpln-organization/group/superusers            |manage  |
    |manage     |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |use        |/org/demo-cpln-organization/group/superusers            |manage  |
    |use        |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    |view       |/org/demo-cpln-organization/group/viewers               |view    |
    |view       |/org/demo-cpln-organization/group/superusers            |manage  |
    |view       |/org/demo-cpln-organization/serviceaccount/controlplane |manage  |
    +-----------+--------------------------------------------------------+--------+
    ```
  </CodeGroup>
</Accordion>

***

#### agent audit

Retrieve audit trail events for the referenced agent

**Usage**

```none theme={null}
cpln agent audit [ref] [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.

  Command options:
    --subject  Filter by subject (serviceaccount name or user email)  [string]
    --context  Audit context name (the 'cpln' context displays Control Plane actions)  [string] [default: "cpln"]
    --since    Relative lookback window from now (e.g., 1h, 24h, 7d). Mutually exclusive with --from/--to  [string] [default: "7d"]
    --from     Start time for audit events (ISO 8601 format or relative duration, e.g., 2025-10-23T07:00:00Z, 7d, 1h). Cannot be used with --since  [string]
    --to       End time for audit events (ISO 8601 format or relative duration, e.g., 2025-10-23T07:00:00Z, 1d, 30m)  [string]

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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>

***

#### agent create

Create a new agent

**Usage**

```none theme={null}
cpln agent create --name AGENT_NAME [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Command options:
    --name                 Name of the agent  [required]
    --description, --desc  Optional description, defaults to the name if not set
    --tag                  Attach tags (e.g., --tag drink=water)

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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 agent create --name demo-agent --desc demo-agent --tag drink=water --org demo-cpln-organization
    ```

    ```text Output theme={null}
    {
      "agentId": "23bbbe5d-91a7-4dd2-862e-86a5e4d31a36",
      "agentLink": "/org/demo-cpln-organization/agent/demo-agent",
      "hubEndpoint": "https://hub.test.cpln.io",
      "registrationToken": "a2O20riaW5Pk0qKPbqYZpCzFbFDdpb5ApFCdmYWb2N7FUogShV_XWIFA/tM9G03",
      "protocolVersion": "v2"
    }
    ```
  </CodeGroup>
</Accordion>

***

#### agent delete

Delete one or more referenced agents

**Usage**

```none theme={null}
cpln agent delete <ref...> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  One or more resource references. Usually it is the name of the resource.  [array] [required] [default: []]

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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 agent delete demo-agent --org demo-cpln-organization
    ```

    ```text Output theme={null}
    If the delete was successful, a new command prompt will be shown.
    ```
  </CodeGroup>
</Accordion>

***

#### agent edit

Edit the referenced agent, as YAML, within an editor

**Usage**

```none theme={null}
cpln agent edit <ref> [OPTIONS]
```

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

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Command options:
    --replace, -r  Replace instead of patch/merge  [boolean] [default: false]

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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 agent edit demo-agent --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.
    ```
  </CodeGroup>
</Accordion>

***

#### agent eventlog

Show the event log of the referenced agent

**Usage**

```none theme={null}
cpln agent eventlog <ref> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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 agent eventlog demo-agent --org demo-cpln-organization
    ```

    ```text Output theme={null}
    The event log for the referenced agent will be shown.
    ```
  </CodeGroup>
</Accordion>

***

#### agent get

Retrieve one or more referenced agents

**Usage**

```none theme={null}
cpln agent get [ref...] [OPTIONS]
```

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

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  One or more resource references. Usually it is the name of the resource.  [array] [default: []]

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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">
  * Get all agents

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent get --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------------+-----------------+--------+--------------+
    |NAME             |DESCRIPTION      |CREATED |TAGS          |
    |-----------------|-----------------|--------|--------------|
    |demo-agent       |demo-agent       |Now     |drink="water" |
    |demo-agent-get-1 |demo-agent-get-1 |Now     |              |
    |demo-agent-get-2 |demo-agent-get-2 |Now     |              |
    +-----------------+-----------------+--------+--------------+
    ```
  </CodeGroup>

  * Get one agent

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent get demo-agent-get-1 --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------------+-----------------+--------+-----+
    |NAME             |DESCRIPTION      |CREATED |TAGS |
    |-----------------|-----------------|--------|-----|
    |demo-agent-get-1 |demo-agent-get-1 |Now     |     |
    +-----------------+-----------------+--------+-----+
    ```
  </CodeGroup>

  * Get multiple agents

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent get demo-agent-get-1 demo-agent-get-2 --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------------+-----------------+--------+-----+
    |NAME             |DESCRIPTION      |CREATED |TAGS |
    |-----------------|-----------------|--------|-----|
    |demo-agent-get-1 |demo-agent-get-1 |Now     |     |
    |demo-agent-get-2 |demo-agent-get-2 |Now     |     |
    +-----------------+-----------------+--------+-----+
    ```
  </CodeGroup>
</Accordion>

***

#### agent info

Get info about an agent

**Usage**

```none theme={null}
cpln agent info <ref> [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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">
  * Return the details of a deployed agent. The example below was for an agent deployed at AWS.

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent info demo-agent --org demo-cpln-organization
    ```

    ```json Output theme={null}
    {
      "env": {
        "cpuPlatform": "x86_64",
        "image": "ami-0fff5e2863a768052",
        "id": "i-01adfe256a82a2a76",
        "machineType": "t2.micro",
        "zone": "us-west-2c",
        "internalIP": "172.31.13.246",
        "hostname": "ip-172-31-13-246.us-west-2.compute.internal",
        "vpc": "vpc-29e3c451",
        "subnet": "subnet-b11e9dec",
        "accountId": "015716931765",
        "cloudProvider": "aws"
      },
      "lastActive": "2021-05-01T00:26:55.945Z",
      "serviceCount": 0,
      "peerCount": 0
    }
    ```
  </CodeGroup>
</Accordion>

***

#### agent manifest

Generate a manifest for running an agent in K8S

**Usage**

```none theme={null}
cpln agent manifest --bootstrap-file FILE_NAME --namespace NAME_SPACE [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Command options:
    --bootstrap-file    Path to the bootstrap config file  [required]
    --namespace, -n     Namespace where the agent deployment(s) will live  [required]
    --image             Advanced use: Use a different agent Docker image
    --cluster           Add metadata to agent's environment, useful to remind you which cluster an agent is running in
    --replicas          Number of agent deployments to create  [default: 1]
    --create-namespace  Create the namespace  [boolean] [default: true]

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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>

***

#### agent patch

Update the referenced agent's metadata using an input file

**Usage**

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

<Note>
  Running this command with the option **`--file -`** sets the input to stdin. The input is required to be a valid JSON or YAML string (e.g., `{"description": "My new description"}` or `description: My new description`). To complete the update, press Control-D (or Control-Z if you are using Windows).
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Command options:
    --file, -f  File to load the patch from. Use `--file -` to enable input from stdin.  [required]

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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 agent patch demo-agent --file update.json --org demo-cpln-organization
    ```

    ```text Output theme={null}
    The changes within the JSON file will be performed against the referenced agent.
    ```
  </CodeGroup>
</Accordion>

***

#### agent permissions

Show the grantable permissions for an agent object type

**Usage**

```none theme={null}
cpln agent permissions [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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 agent permissions --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-------+----------------------------+----------------------------------------+
    |NAME   |DESCRIPTION                 |IMPLIES                                 |
    |-------|----------------------------|----------------------------------------|
    |create |Create new agents           |                                        |
    |delete |Delete service agents       |                                        |
    |edit   |Modify existing agents      |view                                    |
    |manage |Full access                 |create, delete, edit, manage, use, view |
    |use    |Use an agent in an identity |view                                    |
    |view   |Read-only access            |                                        |
    +-------+----------------------------+----------------------------------------+
    ```
  </CodeGroup>
</Accordion>

***

#### agent query

Find all the agents based on the given query

**Usage**

```none theme={null}
cpln agent query QUERY_OPTIONS [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Query options:
    --match             Query filter type  [choices: "all", "none", "any"] [default: "all"]
    --property, --prop  Property to query
    --tag               Tag to query
    --rel               Relation to query

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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">
  <Note>
    Use the `--match` option to display **all**, **none**, or **any** of the results based on a given property or tag
  </Note>

  * Search for an agent based on the name property

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent query --match any --prop name=demo-agent --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED |TAGS          |
    |-----------|------------|--------|--------------|
    |demo-agent |demo-agent  |Now     |drink="water" |
    +-----------+------------+--------+--------------+
    ```
  </CodeGroup>

  * Search for an agent based on the description property

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent query --match any --prop description="demo-agent" --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED |TAGS          |
    |-----------|------------|--------|--------------|
    |demo-agent |demo-agent  |Now     |drink="water" |
    +-----------+------------+--------+--------------+
    ```
  </CodeGroup>

  * Search for an agent based on a tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent query --match any --tag drink=water --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED |TAGS          |
    |-----------|------------|--------|--------------|
    |demo-agent |demo-agent  |Now     |drink="water" |
    +-----------+------------+--------+--------------+
    ```
  </CodeGroup>

  * Search for an agent based on a property and tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent query --match any --prop description="demo-agent" --tag drink=water --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED |TAGS          |
    |-----------|------------|--------|--------------|
    |demo-agent |demo-agent  |Now     |drink="water" |
    +-----------+------------+--------+--------------+
    ```
  </CodeGroup>
</Accordion>

***

#### agent tag

Manage the tags belonging to one or more referenced agents

**Usage**

```none theme={null}
cpln agent tag <ref...> --tag KEY=VALUE [OPTIONS]
```

<Note>
  Built-in tags, which begin with cpln/\*, can't be modified.
</Note>

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  One or more resource references. Usually it is the name of the resource.  [array] [required] [default: []]

  Command options:
    --tag         Attach tags (e.g., --tag drink=water)
    --remove-tag  Remove tags (e.g., --remove-tag tagname)

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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">
  * Add a tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent tag demo-agent --tag drink=water --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------+--------------+
    |NAME       |DESCRIPTION |CREATED |TAGS          |
    |-----------|------------|--------|--------------|
    |demo-agent |demo-agent  |Now     |drink="water" |
    +-----------+------------+--------+--------------+
    ```
  </CodeGroup>

  * Update same tag (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent tag demo-agent --tag drink=coffee --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------+---------------+
    |NAME       |DESCRIPTION |CREATED |TAGS           |
    |-----------|------------|--------|---------------|
    |demo-agent |demo-agent  |Now     |drink="coffee" |
    +-----------+------------+--------+---------------+
    ```
  </CodeGroup>

  * Remove tag (after running the example above)

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent tag demo-agent --remove drink --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +-----------+------------+--------+-----+
    |NAME       |DESCRIPTION |CREATED |TAGS |
    |-----------|------------|--------|-----|
    |demo-agent |demo-agent  |Now     |     |
    +-----------+------------+--------+-----+
    ```
  </CodeGroup>
</Accordion>

***

#### agent up

Run an agent within a local Docker instance

**Usage**

```none theme={null}
cpln agent up --bootstrap-file FILE_NAME [--background] [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Command options:
    --bootstrap-file   Path to the bootstrap config file  [required]
    --background, -b   If set, run the agent as a background process  [boolean]
    --image            Advanced use: Use a different agent Docker image
    --net              Docker network to use  [default: "bridge"]
    --exposeProxy, -p  Expose port 3128 if agent is to be used as forward proxy. Has no effect on v1 agents  [boolean]

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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 agent up --bootstrap-file bootstrap.config --org demo-cpln-organization
    ```

    ```text Output theme={null}
    The Control Plane agent will be executed in a local Docker instance using the referenced bootstrap config file
    ```
  </CodeGroup>
</Accordion>

***

#### agent update

Update properties of the referenced agent

**Usage**

```none theme={null}
cpln agent update <ref> --set UPDATE_PROPERTY [OPTIONS]
```

<Accordion title="Reference">
  ```text theme={null}
  Positionals:
    ref  The resource reference. Usually it is the name of the resource.  [required]

  Update Properties:
    --set    Update the following properties (e.g., --set description="Updated Description"):

             description    string
             tags.<key>     string
    --unset  Unset a property (same paths as --set, e.g., --unset description)

  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
    --org      Override the organization. The default organization can be set in your profile by using the `cpln profile update` command

  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="Options">
  * The `--set` option allows the modification of the following agent properties:
    * `description`
      * Description of the agent
      * Type: string
    * `tags`
      * Tags (key=value) associated with the agent
      * Type: string
</Accordion>

<Accordion title="Example">
  * For the examples below, the initial agent is configured as:

  ```
  +------------------+------------------+--------+-----+
  |NAME              |DESCRIPTION       |CREATED |TAGS |
  |------------------|------------------|--------|-----|
  |demo-agent-update |demo-agent-update |Now     |     |
  +------------------+------------------+--------+-----+
  ```

  * Update an agent's description

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent update demo-agent-update --set description="new description" --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +------------------+----------------+--------+-----+
    |NAME              |DESCRIPTION     |CREATED |TAGS |
    |------------------|----------------|--------|-----|
    |demo-agent-update |new description |Now     |     |
    +------------------+----------------+--------+-----+
    ```
  </CodeGroup>

  * Update an agent's tag

  <CodeGroup>
    ```bash Command theme={null}
    cpln agent update demo-agent-update --set tags.demo-key=demo-value --org demo-cpln-organization
    ```

    ```text Output theme={null}
    +------------------+----------------+--------+----------------------+
    |NAME              |DESCRIPTION     |CREATED |TAGS                  |
    |------------------|----------------|--------|----------------------|
    |demo-agent-update |new description |Now     |demo-key="demo-value" |
    +------------------+----------------+--------+----------------------+
    ```
  </CodeGroup>
</Accordion>

***