diff --git a/docs.json b/docs.json index 8e839d8..76480d7 100644 --- a/docs.json +++ b/docs.json @@ -265,6 +265,7 @@ "reference/cli/auth", "reference/cli/browsers", "reference/cli/apps", + "reference/cli/managed-auth", "reference/cli/projects", "reference/cli/api-keys", "reference/cli/mcp", diff --git a/reference/cli.mdx b/reference/cli.mdx index edcb503..7a4e39c 100644 --- a/reference/cli.mdx +++ b/reference/cli.mdx @@ -37,6 +37,9 @@ kernel --version Deploy apps, invoke actions, and stream logs. + + Manage auth connections, credentials, and credential providers. + Upload, download, and build browser extensions. @@ -91,6 +94,26 @@ kernel deploy index.ts -o json See individual command documentation for JSON output availability. +## Utility Commands + +### `kernel status` +Check the operational status of Kernel services. + +- `--output json`, `-o json` - Output raw JSON object. + +### `kernel upgrade` +Upgrade the Kernel CLI to the latest version. + +- `--dry-run` - Show what would be executed without running it. + +### `kernel completion ` +Generate a shell autocompletion script (`bash`, `zsh`, `fish`, or `powershell`). + +```bash +# Load completions for the current zsh session +source <(kernel completion zsh) +``` + Looking for the API? See the [API Reference](https://kernel.sh/docs/api-reference/invocations/invoke-an-action). diff --git a/reference/cli/managed-auth.mdx b/reference/cli/managed-auth.mdx new file mode 100644 index 0000000..224b1fd --- /dev/null +++ b/reference/cli/managed-auth.mdx @@ -0,0 +1,216 @@ +--- +title: "Managed Auth" +--- + +Manage [managed auth](/auth/overview) connections, stored credentials, and external credential providers from the CLI. For authenticating the CLI itself (login, logout, API keys), see [Authentication](/reference/cli/auth). + +## Connections +A managed auth connection keeps a [profile](/auth/profiles) logged into a domain so future browsers reuse the authenticated session. See [Managed auth](/auth/overview) for concepts and the [programmatic flow](/auth/programmatic) for the SDK equivalent. + +### `kernel auth connections create` +Create a managed auth connection for a profile and domain. + +| Flag | Description | +|------|-------------| +| `--profile-name ` | Name of the profile to manage (required). | +| `--domain ` | Target domain for authentication (required). | +| `--allowed-domain ` | Additional allowed domains (repeatable). | +| `--login-url ` | Login page URL to skip discovery. | +| `--health-check-interval ` | Seconds between health checks (300–86400). | +| `--proxy-id ` | Proxy ID to use. | +| `--proxy-name ` | Proxy name to use. | +| `--credential-provider ` | External credential provider name. | +| `--credential-name ` | Kernel credential name to use. | +| `--credential-path ` | Provider-specific path (e.g. `VaultName/ItemName`). | +| `--credential-auto` | Look up the credential by domain from the provider (defaults to true when `--credential-provider` is set without `--credential-path`). | +| `--no-save-credentials` | Don't save credentials after a successful login. | +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel auth connections list` +List managed auth connections. + +| Flag | Description | +|------|-------------| +| `--domain ` | Filter by domain. | +| `--profile-name ` | Filter by profile name. | +| `--limit ` | Maximum number of results to return. | +| `--offset ` | Number of results to skip. | +| `--output json`, `-o json` | Output raw JSON array. | + +### `kernel auth connections get ` +Get a managed auth connection by ID. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel auth connections login ` +Start a login flow and return a hosted URL for authentication. + +| Flag | Description | +|------|-------------| +| `--proxy-id ` | Proxy ID to use for this login. | +| `--proxy-name ` | Proxy name to use for this login. | +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel auth connections submit ` +Submit field values to an in-progress login flow. Poll the connection (or use `follow`) to track progress. + +| Flag | Description | +|------|-------------| +| `--field ` | Field name/value pair (repeatable). | +| `--mfa-option-id ` | MFA option ID when an MFA method was selected. | +| `--sign-in-option-id ` | Sign-in option ID when the flow returned non-MFA choices. | +| `--sso-button-selector ` | XPath selector when choosing an SSO button. | +| `--sso-provider ` | SSO provider when choosing by provider (e.g. `google`, `github`). | +| `--output json`, `-o json` | Output raw JSON object. | + +```bash +# Submit username and password +kernel auth connections submit --field username=myuser --field password=mypass + +# Select an MFA option +kernel auth connections submit --mfa-option-id +``` + +### `kernel auth connections follow ` +Stream real-time login flow state updates over SSE. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o json` | Output raw JSON events. | + +### `kernel auth connections update ` +Update connection settings such as login URL, health checks, credential source, and proxy. + +| Flag | Description | +|------|-------------| +| `--login-url ` | Login page URL (set to an empty string to clear). | +| `--allowed-domain ` | Additional allowed domains (replaces the existing list). | +| `--health-check-interval ` | Seconds between health checks. | +| `--proxy-id ` | Proxy ID to use. | +| `--proxy-name ` | Proxy name to use. | +| `--credential-provider ` | External credential provider name. | +| `--credential-name ` | Kernel credential name to use. | +| `--credential-path ` | Provider-specific path (e.g. `VaultName/ItemName`). | +| `--credential-auto` | Look up the credential by domain from the provider. | +| `--save-credentials` | Save credentials after a successful login. | +| `--no-save-credentials` | Don't save credentials after a successful login. | +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel auth connections delete ` +Delete a managed auth connection. + +| Flag | Description | +|------|-------------| +| `--yes`, `-y` | Skip the confirmation prompt. | + +## Credentials +Store login field values, TOTP secrets, and SSO settings that managed auth connections use to authenticate. See [Credentials](/auth/credentials) for concepts. + +### `kernel credentials create` +Create a new credential. + +| Flag | Description | +|------|-------------| +| `--name ` | Unique name for the credential (required). | +| `--domain ` | Target domain this credential is for (required). | +| `--value ` | Field name/value pair (repeatable, e.g. `--value username=myuser --value password=mypass`). | +| `--totp-secret ` | Base32-encoded TOTP secret for 2FA. | +| `--sso-provider ` | SSO provider (e.g. `google`, `github`, `microsoft`). | +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel credentials list` +List credentials. + +| Flag | Description | +|------|-------------| +| `--domain ` | Filter by domain. | +| `--limit ` | Maximum number of results to return. | +| `--offset ` | Number of results to skip. | +| `--output json`, `-o json` | Output raw JSON array. | + +### `kernel credentials get ` +Get a credential by ID or name. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel credentials update ` +Update a credential. + +| Flag | Description | +|------|-------------| +| `--name ` | New name for the credential. | +| `--value ` | Field name/value pair to update (repeatable). | +| `--totp-secret ` | Base32-encoded TOTP secret (set to an empty string to remove). | +| `--sso-provider ` | SSO provider (set to an empty string to remove). | +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel credentials totp-code ` +Print the current TOTP code for a credential. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel credentials delete ` +Delete a credential by ID or name. + +## Credential providers +Connect an external secrets manager (e.g. 1Password) so managed auth connections can look up credentials at login time instead of storing them in Kernel. + +### `kernel credential-providers create` +Register a new credential provider. + +| Flag | Description | +|------|-------------| +| `--provider-type ` | Provider type (e.g. `onepassword`). | +| `--name ` | Human-readable name for this provider instance. | +| `--token ` | Service account token for the provider. | +| `--cache-ttl ` | How long to cache credential lists (default: 300). | +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel credential-providers list` +List credential providers. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o json` | Output raw JSON array. | + +### `kernel credential-providers get ` +Get a credential provider by ID. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel credential-providers list-items ` +List items available from a credential provider. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o json` | Output raw JSON array. | + +### `kernel credential-providers test ` +Test the connection to a credential provider. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel credential-providers update ` +Update a credential provider. + +| Flag | Description | +|------|-------------| +| `--name ` | New human-readable name. | +| `--token ` | New service account token (to rotate credentials). | +| `--cache-ttl ` | How long to cache credential lists. | +| `--enabled` | Whether the provider is enabled for credential lookups. | +| `--priority ` | Priority for credential lookups (lower numbers are checked first). | +| `--output json`, `-o json` | Output raw JSON object. | + +### `kernel credential-providers delete ` +Delete a credential provider.