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

# Authentication & login

The `auth` command group handles SSO authentication: log in through the browser and store short-lived STS credentials, clear the session, show the current identity, manage login profiles, and prepare CLI SSO login resources for an organization. `login`, `logout`, and `whoami` are also available as top-level commands (e.g. `agentkit login`).

## auth login

Authenticate via browser SSO and store short-lived STS credentials.

| Flag / Argument | Description | Default |
| - | - | - |
| `[address]` | Login address | None |
| `-p, --profile <name>` | Use a named, pre-seeded profile instead of an address | None |
| `--duration <seconds>` | Requested STS credential lifetime (seconds) | `3600` |
| `--no-open` | Don't open a browser — just print the login URL (headless/SSH) | `false` |

```bash lines theme={null}
agentkit auth login
```

## auth logout

Clear the stored SSO session (refresh token + cached STS credentials).

| Flag / Argument | Description | Default |
| - | - | - |
| `-p, --profile <name>` | SSO profile name | Active profile |
| `--all` | Clear every profile's session | `false` |

```bash lines theme={null}
agentkit auth logout
```

## auth whoami

Show the identity behind the current credentials.

| Flag / Argument | Description | Default |
| - | - | - |
| `-p, --profile <name>` | SSO profile name | Active profile |

```bash lines theme={null}
agentkit auth whoami
```

## auth profile set

Create or update a profile's login coordinates (non-secret).

| Flag / Argument | Description | Default |
| - | - | - |
| `<name>` | Profile name (required) | None |
| `--issuer <url>` | OIDC issuer URL | None |
| `--client-id <id>` | Public OAuth client id | None |
| `--role-trn <trn>` | STS role TRN | None |
| `--provider-trn <trn>` | IAM OIDC provider TRN | None |
| `--region <region>` | Region | `cn-beijing` |

```bash lines theme={null}
agentkit auth profile set my-profile --issuer https://example.com --client-id abc123
```

## auth profile list

List saved profiles.

This command takes no arguments or options.

```bash lines theme={null}
agentkit auth profile list
```

## auth profile show

Show a profile's coordinates.

| Flag / Argument | Description | Default |
| - | - | - |
| `[name]` | Profile name | Active profile |

```bash lines theme={null}
agentkit auth profile show my-profile
```

## auth admin doctor

Run read-only checks that determine whether the account is ready for CLI SSO setup, including identity permissions and credential-hosting prerequisites. Failed checks produce a nonzero exit code and remediation guidance.

| Flag / Argument | Description | Default |
| - | - | - |
| `--account <account>` | Expected account ID; refuse to continue when the active credentials belong to another account | — |
| `--region <region>` | Cloud region | Current provider's default region |
| `--data-plane` | Also check credential-hosting prerequisites | `true` |
| `--no-data-plane` | Skip credential-hosting prerequisite checks | — |

```bash lines theme={null}
agentkit auth admin doctor --account <account-id> --region cn-beijing
```

## auth admin create-userpool

Create a user pool for CLI SSO login and output its ID as JSON.

<Warning>
  This command creates an identity resource in the selected account and region. Run `auth admin doctor` first to check the account, region, and permissions.
</Warning>

| Flag / Argument | Description | Default |
| - | - | - |
| `--name <name>` | User pool name (required) | — |
| `--account <account>` | Expected account ID; refuse to continue when the active credentials belong to another account | — |
| `--region <region>` | Cloud region | Current provider's default region |

```bash lines theme={null}
agentkit auth admin create-userpool --name agentkit-cli-pool --account <account-id>
```

## auth admin provision

Create or reuse a public CLI client, IAM OIDC provider, and STS role for an existing user pool, then output the login discovery configuration.

<Warning>
  This command modifies user-pool and IAM resources. Confirm that the user pool belongs to the target account and region, and grant the role only the permissions required by CLI users.
</Warning>

| Flag / Argument | Description | Default |
| - | - | - |
| `--user-pool <uid>` | User pool ID (required) | — |
| `--account <account>` | Expected account ID; refuse to continue when the active credentials belong to another account | — |
| `--region <region>` | Cloud region | Current provider's default region |

```bash lines theme={null}
agentkit auth admin provision --user-pool <user-pool-id> --account <account-id>
```

## auth admin sso-setup

Prepare the user pool, public CLI client, IAM OIDC provider, STS role, and TOS-hosted login discovery document in one flow. The command prints an `agentkit login <address>` address that can be distributed to CLI users. In an interactive terminal it asks whether to reuse a user pool, configure an upstream identity provider, and use a custom domain. Non-interactive runs use defaults or explicit flags.

<Warning>
  This command creates or modifies identity, IAM, and TOS resources and publishes a publicly accessible login discovery document. An upstream identity provider secret is sensitive. Prefer entering it through the hidden interactive prompt instead of saving it in a repository or shell history.
</Warning>

| Flag / Argument | Description | Default |
| - | - | - |
| `-y, --yes` | Run non-interactively with defaults and explicitly provided flags | `false` |
| `--user-pool <uid>` | Reuse an existing user pool | — |
| `--create-pool <name>` | Create a user pool with this name | `agentkit-cli-pool` |
| `--account <account>` | Expected account ID; refuse to continue when the active credentials belong to another account | Account for the active credentials |
| `--region <region>` | Cloud region | Current provider's default region |
| `--idp <type>` | Upstream identity provider: `bytedance` \| `feishu` | No upstream identity provider |
| `--idp-client-id <id>` | Upstream identity provider client ID; in non-interactive mode, use it with `--idp-secret` | — |
| `--idp-secret <secret>` | Upstream identity provider client secret | — |
| `--bucket <bucket>` | TOS bucket that hosts the login discovery document | `agentkit-cli-<account-id>` |
| `--domain <domain>` | Custom HTTPS login domain | HTTPS address of the TOS bucket |
| `--client-name <name>` | Public CLI user-pool client name | Built-in CLI name |
| `--provider-name <name>` | IAM OIDC provider name | Built-in CLI name |
| `--role-name <name>` | STS role name | Built-in CLI name |

```bash lines theme={null}
# Interactive setup; enter sensitive upstream credentials in the hidden prompt
agentkit auth admin sso-setup --account <account-id> --region cn-beijing

# Reuse an existing user pool in automation
agentkit auth admin sso-setup --yes \
  --user-pool <user-pool-id> \
  --account <account-id> \
  --bucket <discovery-bucket>
```

## auth admin publish

Create or reuse the CLI login resources for an existing user pool and publish the `/.well-known/agentkit-cli` discovery document to a selected TOS bucket.

<Warning>
  This command modifies identity and IAM resources and writes public login configuration to the selected bucket. Confirm that the bucket, account, and user pool belong to the target environment.
</Warning>

| Flag / Argument | Description | Default |
| - | - | - |
| `--user-pool <uid>` | User pool ID (required) | — |
| `--bucket <bucket>` | TOS bucket that hosts the discovery document (required) | — |
| `--account <account>` | Expected account ID; refuse to continue when the active credentials belong to another account | — |
| `--region <region>` | Cloud region | Current provider's default region |

```bash lines theme={null}
agentkit auth admin publish \
  --user-pool <user-pool-id> \
  --bucket <discovery-bucket> \
  --account <account-id>
```