> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/commander-sdk/keeper-commander-sdks/sdk-command-reference/keeperpam-commands/pam-config-commands.md).

# PAM Config Commands

View, create, edit and remove Keeper PAM Configurations. To learn more about PAM Configurations click here.

### Config List command

Lists all configs accessible by the Commander user.

<details>

<summary>DotNet CLI</summary>

**Command**: `pam-config list`

**Alias**: `pam-cfg list` / `pam-cfg l`

**Parameters**:

<table><thead><tr><th width="243">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>&#x3C;uid></code> (positional)</td><td>Configuration UID or name. When set, shows detail for one config</td></tr><tr><td><code>--verbose</code>, <code>-v</code></td><td>Include field details (and allowed settings in JSON detail)</td></tr><tr><td><code>--format {table,json}</code></td><td>Output format. Default: <code>table</code></td></tr></tbody></table>

**Examples**:

{% code expandable="true" %}

```csharp
My Vault> pam-config list
UID                     Config Name          Config Type              Shared Folder                         Gateway UID             Resource Record UIDs 
----------------------  -------------------  -----------------------  ------------------------------------  ----------------------  -------------------- 
r0GEhXL8fQabsgtY3f_cyy_--w  Gate1 Configuration  pamNetworkConfiguration  SF2 - Users (W8eQhS6wcrnahayDldSbgCb_h8A)  UorQhjoeTNmsuGA4rRzcNd-fQ
m-KTGmajats9e7INjefCVZsnxw  Test-CONFIG-14TH     pamNetworkConfiguration  SF2 - Users (W8ensgaQhS6wcrDldSbgCb_h8A)  UorQhjoeTNGlaiyA4rRzcNd-fQ
```

{% endcode %}

</details>

<details>

<summary>DotNet SDK</summary>

**Function:**

```csharp
    public static Dictionary<string, TypedRecord> GetConfigurationRecords(VaultOnline vault)
    {
      if (vault == null)
      {
        return new Dictionary<string, TypedRecord>();
      }

      return vault.KeeperRecords
        .OfType<TypedRecord>()
        .Where(x => PamRecordTypes.Configuration.Contains(x.TypeName ?? ""))
        .ToDictionary(x => x.Uid, x => x);
    }
```

</details>

<details>

<summary>Power Commander</summary>

**Command**: `Get-KeeperPamConfig`\
**Alias**: `pam-config-list / pam-cfg-list`

**Parameters:**

<table><thead><tr><th width="264">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>Config / -c</code></td><td>Specific PAM Configuration UID or title</td></tr><tr><td><code>-VerboseOutput / -v</code></td><td>Verbose output</td></tr><tr><td><code>-Format</code></td><td>Output format {table,json} (default: table)</td></tr></tbody></table>

**Examples**:

```powershell
PS > Get-KeeperPamConfig
Uid                    ConfigName      ConfigType               SharedFolder                    GatewayUid            ResourceRecordUids
---                    ----------      ----------               ------------                    ----------            ------------------
abc123...              Network Config  pamNetworkConfiguration  Pam Folder (sfUid...)           AN1Y-2MzTK6E...       recUid1, recUid2

PS > Get-KeeperPamConfig -Config "<CONFIG_UID>" -VerboseOutput
PS > pam-config-list -c "<CONFIG_UID>" -Format json

```

</details>

<details>

<summary>Python CLI</summary>

**Command: Coming Soon**

</details>

<details>

<summary>Python SDK</summary>

**Command: Coming Soon**

</details>

### Config Create command

Creates a PAM Configuration record, moves it into the shared folder, optionally binds a gateway, and applies tunneling/feature permissions.

<details>

<summary>DotNet CLI</summary>

**Command**: `pam-config new`

**Alias**: `pam-cfg new` / `pam-cfg n`

**Parameters**:

<table data-search="false"><thead><tr><th width="263">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>--environment</code></td><td>Config type: <code>local</code>, <code>network</code>, <code>aws</code>, <code>azure</code>, <code>gcp</code>, <code>domain</code>, <code>oci</code>, <code>github</code></td></tr><tr><td><code>--title</code>, <code>-t</code></td><td>Title of the PAM Configuration</td></tr><tr><td><code>--shared-folder</code></td><td>Shared folder UID, name, or path (e.g. <code>PAM/TestFolder</code>)</td></tr><tr><td><code>--gateway</code>, <code>-g</code></td><td>Gateway UID or name</td></tr><tr><td><code>--schedule</code></td><td>Default rotation schedule CRON (e.g. <code>0 0 2 * * ?</code>) or <code>On-Demand</code></td></tr><tr><td><code>--port-mapping</code></td><td>Port mapping entry (repeatable)</td></tr><tr><td><code>--identity-provider</code></td><td>Identity Provider UID</td></tr><tr><td><code>--connections</code>, <code>-c</code></td><td>Connections permissions: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--tunneling</code>, <code>-u</code></td><td>Tunneling permissions: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--rotation</code>, <code>-r</code></td><td>Rotation permissions: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--remote-browser-isolation</code></td><td>RBI permissions: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--connections-recording</code></td><td>Session recording: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--typescript-recording</code></td><td>TypeScript recording: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--ai-threat-detection</code></td><td>AI threat detection: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--ai-terminate-session-on-detection</code></td><td>AI session terminate on detection: <code>on</code>, <code>off</code>, <code>default</code></td></tr></tbody></table>

Network (`local` / `network`):

<table><thead><tr><th width="263">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>--network-id</code></td><td>Network ID</td></tr><tr><td><code>--network-cidr</code></td><td>Network CIDR</td></tr></tbody></table>

AWS:

<table><thead><tr><th width="263">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>--aws-id</code></td><td>AWS ID</td></tr><tr><td><code>--access-key-id</code></td><td>Access key ID</td></tr><tr><td><code>--access-secret-key</code></td><td>Access secret key</td></tr><tr><td><code>--region-name</code></td><td>Region name(s) (repeatable)</td></tr></tbody></table>

Azure:

<table><thead><tr><th width="263">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>--azure-id</code></td><td>Azure ID</td></tr><tr><td><code>--client-id</code></td><td>Client ID</td></tr><tr><td><code>--client-secret</code></td><td>Client secret</td></tr><tr><td><code>--subscription-id</code></td><td>Subscription ID</td></tr><tr><td><code>--tenant-id</code></td><td>Tenant ID</td></tr><tr><td><code>--resource-group</code></td><td>Resource group(s) (repeatable)</td></tr></tbody></table>

GCP:

<table><thead><tr><th width="263">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>--gcp-id</code></td><td>GCP ID</td></tr><tr><td><code>--service-account-key</code></td><td>Service account key JSON</td></tr><tr><td><code>--google-admin-email</code></td><td>Google Workspace admin email</td></tr><tr><td><code>--gcp-region</code></td><td>GCP region name(s) (repeatable)</td></tr></tbody></table>

Domain:

<table data-search="false"><thead><tr><th width="263">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>--domain-id</code></td><td>Domain ID</td></tr><tr><td><code>--domain-hostname</code></td><td>Domain hostname</td></tr><tr><td><code>--domain-port</code></td><td>Domain port</td></tr><tr><td><code>--domain-use-ssl</code></td><td>Use SSL: <code>true</code>, <code>false</code></td></tr><tr><td><code>--domain-scan-dc-cidr</code></td><td>Scan DC CIDR: <code>true</code>, <code>false</code></td></tr><tr><td><code>--domain-network-cidr</code></td><td>Domain network CIDR</td></tr><tr><td><code>--domain-admin</code></td><td>Domain administrative credential (UID/title)</td></tr><tr><td><code>--domain-user-match</code></td><td>Domain user match filter</td></tr><tr><td><code>--force-domain-admin</code></td><td>Treat <code>--domain-admin</code> as a raw UID</td></tr></tbody></table>

OCI / GitHub:

<table><thead><tr><th width="262">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>--oci-id</code>, <code>--oci-admin-id</code>, <code>--oci-admin-public-key</code>, <code>--oci-admin-private-key</code>, <code>--oci-tenancy</code>, <code>--oci-region</code></td><td>OCI fields (environment not supported yet)</td></tr></tbody></table>

`oci` and `github` are recognized but not supported yet (coming soon).

**Examples**:

{% code expandable="true" %}

```csharp
My Vault> pam-config new --environment local --title "Local Network" --shared-folder W8eQhamahsyS6wcrDldSbgCb_h8A --gateway UorQhjoeTNGAnhay4rRzcNd-fQ --network-id "corp-net" --network-cidr "10.0.0.0/24"
qNmCaiSQbd-ymgZpjauhamTuaYQ
```

{% endcode %}

</details>

<details>

<summary>DotNet SDK</summary>

**Function:**

```csharp
public static TypedRecord CreateConfigurationRecord(VaultOnline vault, string recordType, string title)
    {
      if (vault == null)
      {
        throw new ArgumentNullException(nameof(vault));
      }

      if (string.IsNullOrWhiteSpace(recordType))
      {
        throw new ArgumentException("Record type is required", nameof(recordType));
      }

      if (string.IsNullOrWhiteSpace(title))
      {
        throw new ArgumentException("Title is required", nameof(title));
      }

      var record = new TypedRecord(recordType) { Title = title.Trim(), Version = 6 };
      vault.AdjustTypedRecord(record);
      return record;
    }
```

</details>

<details>

<summary>Power Commander</summary>

**Command**: `New-KeeperPamConfig`

**Alias**: `pam-config-new`

**Parameters:**

<table data-search="false"><thead><tr><th width="264">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>-Environment / -env</code></td><td>PAM Configuration Type {local,aws,azure,gcp,domain,oci,network,github}</td></tr><tr><td><code>-Title / -t</code></td><td>Title of the PAM Configuration</td></tr><tr><td><code>-SharedFolder / -sf / -shared-folder</code></td><td>Shared Folder UID, name, or path</td></tr><tr><td><code>-Gateway / -g</code></td><td>Gateway UID or Name</td></tr><tr><td><code>-DefaultSchedule / -sc / -schedule</code></td><td>Default Schedule (CRON syntax)</td></tr><tr><td><code>-PortMapping / -pm / -port-mapping</code></td><td>Port Mapping</td></tr><tr><td><code>-IdentityProvider / -idp</code></td><td>Identity Provider UID</td></tr><tr><td><code>-Connections / -c</code></td><td>on,off,default</td></tr><tr><td><code>-Tunneling / -u</code></td><td>on,off,default</td></tr><tr><td><code>-Rotation / -r</code></td><td>on,off,default</td></tr><tr><td><code>-RemoteBrowserIsolation / -rbi</code></td><td>on,off,default</td></tr><tr><td><code>-ConnectionsRecording / -cr</code></td><td>on,off,default</td></tr><tr><td><code>-TypescriptRecording / -tr</code></td><td>on,off,default</td></tr><tr><td><code>-AiThreatDetection / -ai-threat-detection</code></td><td>on,off,default</td></tr><tr><td><code>-ai-terminate-session-on-detection</code></td><td>on,off,default</td></tr></tbody></table>

**network:**

<table><thead><tr><th width="264">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>NetworkId / -network-id</code></td><td>Network ID</td></tr><tr><td><code>-NetworkCidr / -network-cidr</code></td><td>Network CIDR</td></tr></tbody></table>

**aws:**

<table><thead><tr><th width="264">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>-AwsId / -aws-id</code></td><td>AWS ID</td></tr><tr><td><code>-AccessKeyId / -access-key-id</code></td><td>Access Key Id</td></tr><tr><td><code>-AccessSecretKey / -access-secret-key</code></td><td>Access Secret Key</td></tr><tr><td><code>-RegionNames / -region-name</code></td><td>Region Names</td></tr></tbody></table>

**azure:**

<table><thead><tr><th width="264">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>-AzureId / -azure-id</code></td><td>Azure Id</td></tr><tr><td><code>-ClientId / -client-id</code></td><td>Client Id</td></tr><tr><td><code>-ClientSecret / -client-secret</code></td><td>Client Secret</td></tr><tr><td><code>-SubscriptionId / -subscription-id</code></td><td>Subscription Id</td></tr><tr><td><code>-TenantId / -tenant-id</code></td><td>Tenant Id</td></tr><tr><td><code>-ResourceGroups / -resource-group</code></td><td>Resource Group</td></tr></tbody></table>

**gcp:**

<table><thead><tr><th width="264">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>-GcpId / -gcp-id</code></td><td>GCP Id</td></tr><tr><td><code>-ServiceAccountKey / -service-account-key</code></td><td>Service Account Key (JSON)</td></tr><tr><td><code>-GoogleAdminEmail / -google-admin-email</code></td><td>Google Workspace Administrator Email</td></tr><tr><td><code>-GcpRegionNames / -gcp-region</code></td><td>GCP Region Names</td></tr></tbody></table>

**domain:**

<table data-search="false"><thead><tr><th width="264">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>-DomainId / -domain-id</code></td><td>Domain ID</td></tr><tr><td><code>-DomainHostname / -domain-hostname</code></td><td>Domain hostname</td></tr><tr><td><code>-DomainPort / -domain-port</code></td><td>Domain port</td></tr><tr><td><code>-DomainUseSsl / -domain-use-ssl</code></td><td>true,false</td></tr><tr><td><code>-DomainScanDcCidr / -domain-scan-dc-cidr</code></td><td>true,false</td></tr><tr><td><code>-DomainNetworkCidr / -domain-network-cidr</code></td><td>Domain Network CIDR</td></tr><tr><td><code>-domain-admin</code></td><td>Domain administrative credential</td></tr><tr><td><code>-DomainUserMatch / -domain-user-match</code></td><td>Domain user match</td></tr><tr><td><code>-ForceDomainAdmin / -force-domain-admin</code></td><td>Force domain admin assignment</td></tr></tbody></table>

**Examples:**

```ps
PS > New-KeeperPamConfig -Environment local -Title "Network Config" -SharedFolder "<SF_UID>" -Gateway "<GATEWAY_UID>" -NetworkId "net1" -NetworkCidr "10.0.0.0/24"
<CONFIG_UID>
PS > pam-config-new -env aws -t "AWS Config" -sf "<SF_UID>" -g "<GATEWAY_UID>" -aws-id "prod" -access-key-id "<KEY>" -access-secret-key "<SECRET>" -region-name "us-east-1"

```

</details>

<details>

<summary>Python CLI</summary>

**Command: Coming Soon**

</details>

<details>

<summary>Python SDK</summary>

**Command: Coming Soon**

</details>

### Config Edit command

Updates an existing PAM Configuration. UID/name is required.

<details>

<summary>DotNet CLI</summary>

**Command**: `pam-config edit`

**Alias**: `pam-cfg edit` / `pam-cfg e`

**Parameters**:

<table data-search="false"><thead><tr><th width="264">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>&#x3C;uid></code> (positional)</td><td>Configuration UID or name</td></tr><tr><td><code>--environment</code></td><td>Change config type (<code>local</code>, <code>network</code>, <code>aws</code>, <code>azure</code>, <code>gcp</code>, <code>domain</code>, …)</td></tr><tr><td><code>--title</code>, <code>-t</code></td><td>New title</td></tr><tr><td><code>--gateway</code>, <code>-g</code></td><td>Gateway UID or name</td></tr><tr><td><code>--shared-folder</code></td><td>Move config to shared folder UID/name/path</td></tr><tr><td><code>--schedule</code></td><td>Default rotation schedule CRON or <code>On-Demand</code></td></tr><tr><td><code>--port-mapping</code></td><td>Port mapping entry (repeatable)</td></tr><tr><td><code>--identity-provider</code></td><td>Identity Provider UID</td></tr><tr><td><code>--remove-resource-record</code></td><td>Resource record UID to unlink (repeatable)</td></tr><tr><td><code>--connections</code>, <code>-c</code></td><td>Connections: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--tunneling</code>, <code>-u</code></td><td>Tunneling: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--rotation</code>, <code>-r</code></td><td>Rotation: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--remote-browser-isolation</code></td><td>RBI: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--connections-recording</code></td><td>Session recording: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--typescript-recording</code></td><td>TypeScript recording: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--ai-threat-detection</code></td><td>AI threat detection: <code>on</code>, <code>off</code>, <code>default</code></td></tr><tr><td><code>--ai-terminate-session-on-detection</code></td><td>AI session terminate: <code>on</code>, <code>off</code>, <code>default</code></td></tr></tbody></table>

Environment-specific fields are the same as `pam-config new` (network / AWS / Azure / GCP / domain / OCI).

**Examples**:

{% code expandable="true" %}

```csharp
My Vault>  pam-config edit qNmCaaiSQbdanhs-ymgZpmTuaYQ --title "Local Network Updated"
PAM configuration "Local Network Updated" updated.
```

{% endcode %}

</details>

<details>

<summary>DotNet SDK</summary>

**Function:**

```csharp
await ConfigUtils.AddConfigurationRecordAsync(vault, record);
await ConfigUtils.EnsureConfigurationNetworkGraphAsync(auth, record.Uid);

if (!string.IsNullOrEmpty(facade.ControllerUid))
{
    await ConfigUtils.SetConfigurationGatewayAsync(auth, record.Uid, facade.ControllerUid);
}

await vault.SyncDown();
await vault.MoveRecordToFolder(
    new RecordPath { RecordUid = record.Uid, FolderUid = sourceFolderUid },
    sharedFolderUid);
```

</details>

<details>

<summary>Power Commander</summary>

**Command**: `Set-KeeperPamConfig`

**Alias:** `pam-config-edit / pam-cfg-edit`

**Parameters:**

<table data-search="false"><thead><tr><th width="264">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>-Uid</code></td><td>PAM Configuration UID or title</td></tr><tr><td><code>-Environment / -env</code></td><td>PAM Configuration Type {local,aws,azure,gcp,domain,oci,network,github}</td></tr><tr><td><code>-Title / -t</code></td><td>Title of the PAM Configuration</td></tr><tr><td><code>-SharedFolder / -sf / -shared-folder</code></td><td>Shared Folder UID, name, or path</td></tr><tr><td><code>-Gateway / -g</code></td><td>Gateway UID or Name</td></tr><tr><td><code>-DefaultSchedule / -sc / -schedule</code></td><td>Default Schedule (CRON syntax)</td></tr><tr><td><code>-PortMapping / -pm / -port-mapping</code></td><td>Port Mapping</td></tr><tr><td><code>-RemoveResourceRecords / -rrr</code></td><td>Resource Record UID(s) to remove</td></tr><tr><td><code>-IdentityProvider / -idp</code></td><td>Identity Provider UID</td></tr><tr><td><code>-Connections / -c</code></td><td>on,off,default</td></tr><tr><td><code>-Tunneling / -u</code></td><td>on,off,default</td></tr><tr><td><code>-Rotation / -r</code></td><td>on,off,default</td></tr><tr><td><code>-RemoteBrowserIsolation / -rbi</code></td><td>on,off,default</td></tr><tr><td><code>-ConnectionsRecording / -cr</code></td><td>on,off,default</td></tr><tr><td><code>-TypescriptRecording / -tr</code></td><td>on,off,default</td></tr><tr><td><code>-AiThreatDetection / -ai-threat-detection</code></td><td>on,off,default</td></tr><tr><td><code>-ai-terminate-session-on-detection</code></td><td>on,off,default</td></tr></tbody></table>

Environment-specific parameters are the same as New-KeeperPamConfig (network/aws/azure/gcp/domain).

**Examples:**

```ps1
PS > Set-KeeperPamConfig -Uid "<CONFIG_UID>" -Title "Updated Title"
PAM configuration "Updated Title" updated.
PS > pam-config-edit "<CONFIG_UID>" -g "<GATEWAY_UID>" -Rotation on
PS > Set-KeeperPamConfig -Uid "<CONFIG_UID>" -RemoveResourceRecords "<RESOURCE_UID>"

```

</details>

<details>

<summary>Python CLI</summary>

**Command: Coming Soon**

</details>

<details>

<summary>Python SDK</summary>

**Command: Coming Soon**

</details>

### Config Remove command

This command is used to remove the configuration.

<details>

<summary>DotNet CLI</summary>

**Command**: `pam-config remove`

**Alias**: `pam-cfg remove` / `pam-cfg rm` / `pam-cfg delete`

**Parameters**:

<table><thead><tr><th width="262">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>&#x3C;uid></code> (positional)</td><td>Configuration UID or name</td></tr></tbody></table>

Examples:

{% code expandable="true" %}

```csharp
My Vault>  pam-config remove qNmCaiSQamshbd-ymgZpmajuymTuaYQ
PAM configuration "Local Network Updated" removed.
```

{% endcode %}

</details>

<details>

<summary>DotNet SDK</summary>

**Function:**

```csharp
    public static async Task RemovePamConfigurationAsync(VaultOnline vault, string configurationUid)
    {
      if (vault == null)
      {
        throw new ArgumentNullException(nameof(vault));
      }

      if (string.IsNullOrEmpty(configurationUid))
      {
        throw new ArgumentException("Configuration UID is required", nameof(configurationUid));
      }

      await PamVaultHelpers.DeletePamConfigurationRecordAsync(vault, configurationUid);
    }
```

</details>

<details>

<summary>Power Commander</summary>

**Command**: `Remove-KeeperPamConfig`

**Alias**: `pam-config-remove / pam-config-rm`

**Parameters**:

<table><thead><tr><th width="264">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>-Uid</code></td><td>PAM Configuration UID or title (required)</td></tr></tbody></table>

**Examples:**

```powershell
PS > Remove-KeeperPamConfig -Uid "<CONFIG_UID>"
PAM configuration "Network Config" removed.
PS > pam-config-remove "<CONFIG_UID>"
PS > pam-config-rm "<CONFIG_UID>"
```

</details>

<details>

<summary>Python CLI</summary>

**Command: Coming Soon**

</details>

<details>

<summary>Python SDK</summary>

**Command: Coming Soon**

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.keeper.io/keeperpam/commander-sdk/keeper-commander-sdks/sdk-command-reference/keeperpam-commands/pam-config-commands.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.