Skip to content

Commit 59d8b9d

Browse files
masnwilliamsmasnwilliams
authored
login, logout, auth commands - oauth vs api key auth (#16)
* login, logout, auth commands - oauth vs api key auth * removed --verbose for log-level logs * Update quickstart guide to clarify Kernel account setup and authentication * updated outdated commands table (this will be overhauled in the near future, but is ok for now)
1 parent 5f1cdf2 commit 59d8b9d

3 files changed

Lines changed: 121 additions & 17 deletions

File tree

‎quickstart.mdx‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ This quickstart guide will help you create, deploy, and run your first app on Ke
88

99
- `brew` for the Kernel CLI
1010
- `npm` or `pnpm` to generate a sample Kernel app
11-
- A [Kernel account](/reference/api-keys) with an API key
11+
- A [Kernel account and authentication setup](/reference/api-keys)
1212

1313
> **Note:** You can also deploy and invoke apps using the [Kernel MCP server](/mcp) from AI assistants (Cursor, Goose, Claude, etc.).
1414
@@ -37,14 +37,26 @@ Verify the installation exists:
3737
which kernel
3838
```
3939

40-
## 3. Set your Kernel API key
40+
## 3. Authenticate with Kernel
4141

42-
Configure your environment with your Kernel API key:
42+
The easiest way to authenticate is using OAuth:
43+
44+
```bash
45+
kernel login
46+
```
47+
48+
This will open your browser to complete the authentication flow. Your credentials will be securely stored and automatically refreshed.
49+
50+
<Info>
51+
Alternatively, you can use an API key for authentication:
4352

4453
```bash
4554
export KERNEL_API_KEY=<YOUR_API_KEY>
4655
```
4756

57+
You can create an API key from the [Kernel dashboard](https://dashboard.onkernel.com).
58+
</Info>
59+
4860
## 4. Deploy the sample app on Kernel
4961

5062
<CodeGroup>

‎reference/api-keys.mdx‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,40 @@
11
---
2-
title: "Creating API Keys"
2+
title: "API Keys"
33
---
44

5-
To get started, sign up for a Kernel account and create an API key [here](https://dashboard.onkernel.com/sign-up). Then follow our [quickstart guide](/quickstart) to launch your first web agent or browser automation.
5+
## Authentication Methods
6+
7+
Kernel supports two authentication methods:
8+
9+
### OAuth 2.0 (Recommended for CLI)
10+
11+
The preferred authentication method to use the CLI is OAuth 2.0, which provides secure browser-based authentication with automatic token refresh:
12+
13+
```bash
14+
kernel login
15+
```
16+
17+
This method stores your credentials securely in your system keychain and handles token refresh automatically.
18+
19+
### API Keys
20+
21+
API keys are an alternative authentication method, particularly useful for programmatic access, CI/CD pipelines, or when OAuth is not suitable:
22+
23+
```bash
24+
export KERNEL_API_KEY=<YOUR_API_KEY>
25+
```
26+
27+
## Creating API Keys
28+
29+
To create an API key:
30+
31+
1. Sign up for a Kernel account [here](https://dashboard.onkernel.com/sign-up)
32+
2. Navigate to your dashboard settings
33+
3. Generate a new API key
34+
4. Store it securely and use it in your environment
35+
36+
## Getting Started
37+
38+
Once you have your authentication set up, follow our [quickstart guide](/quickstart) to launch your first web agent or browser automation.
639

740
You can find information about pricing on our [website](https://www.onkernel.com/#pricing).

‎reference/cli.mdx‎

Lines changed: 71 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,31 @@ Install the Kernel CLI using your favorite package manager:
1313
brew install onkernel/tap/kernel
1414

1515
# Using pnpm
16-
pnpm install -g onkernel/cli
16+
pnpm install -g @onkernel/cli
1717

1818
# Using npm
19-
npm install -g onkernel/cli
19+
npm install -g @onkernel/cli
2020
```
2121

22-
Then, set your Kernel API key for deployments
22+
## Authentication
23+
24+
The Kernel CLI supports two authentication methods:
25+
26+
### OAuth 2.0 (Recommended)
27+
28+
The preferred method is OAuth 2.0 with PKCE, which provides secure browser-based authentication:
29+
30+
```bash
31+
# Login via browser
32+
kernel login
33+
```
34+
35+
This opens your browser to complete the OAuth flow. Your tokens are securely stored in your system keychain (macOS/Windows) or a local file (Linux).
36+
37+
### API Key
38+
39+
You can also authenticate using an API key:
40+
2341
```bash
2442
export KERNEL_API_KEY=<API_KEY>
2543
```
@@ -31,20 +49,61 @@ After installation, verify that Kernel CLI was installed correctly:
3149
which kernel
3250
```
3351

34-
## Commands
52+
## Global Flags
53+
54+
| Flag | Description |
55+
|------|-------------|
56+
| `--version`, `-v` | Print the CLI version |
57+
| `--no-color` | Disable color output |
58+
| `--log-level <level>` | Set the log level (trace, debug, info, warn, error, fatal, print) |
59+
60+
## Authentication Commands
61+
62+
| Command | Description |
63+
|---------|-------------|
64+
| `kernel login [--force]` | Initiates OAuth 2.0 authentication flow via browser. Use `--force` to re-authenticate when already logged in |
65+
| `kernel logout` | Clears stored authentication tokens and logs out |
66+
| `kernel auth` | Displays current authentication status, user details, and token expiry. Use `--log-level debug` for detailed information including user ID and storage method |
67+
68+
## App Management Commands
3569

3670
| Command | Optional Flags | Description |
3771
|---------|-------------| -------------|
3872
| `kernel deploy <entrypoint_file_name>` | - | Deploys an app to Kernel from the current directory. |
39-
| | `--env <ENV_VAR=VAL>` | Adds environment variables to the app. Expects the form `ENV_VAR=VAL` delimited by spaces. Optional. |
73+
| | `--version <version>` | Specify a version for the app (default: latest). Optional. |
74+
| | `--force` | Allow overwrite of an existing version with the same name. Optional. |
75+
| | `--env <ENV_VAR=VAL>`, `-e` | Adds environment variables to the app. Expects the form `ENV_VAR=VAL` delimited by spaces. May be specified multiple times. Optional. |
76+
| | `--env-file <file>` | Read environment variables from a file (.env format). May be specified multiple times. Optional. |
4077
| `kernel invoke <app_name> <action_name>` | - | Invokes a specific app action by its name. Generates an Invocation. |
41-
| | `--payload <payload_data>` | Includes the specified parameters. Expects a stringified JSON object. Optional. |
78+
| | `--version <version>`, `-v` | Specify a version of the app to invoke (default: latest). Optional. |
79+
| | `--payload <payload_data>`, `-p` | Includes the specified parameters. Expects a stringified JSON object. Optional. |
80+
| | `--sync`, `-s` | Invoke synchronously (default false). A synchronous invocation opens a long-lived HTTP POST that times out after 60 seconds. Optional. |
4281
| | `ctrl-c` | Terminates the running invocation in your CLI. Also destroys any associated browsers. |
82+
| `kernel app list` | - | List deployed application versions. |
83+
| | `--name <app_name>` | Filter by application name. Optional. |
84+
| | `--version <version>` | Filter by version label. Optional. |
85+
| `kernel app history <app_name>` | - | Show deployment history for an application. |
4386
| `kernel logs <app_name>` | - | Prints the logs for the specified app. |
44-
| | `--follow` | Follows the logs. Optional. |
45-
| | `--log-level <log_level>` | Specify the log level to print: trace, debug, info, warn, error, fatal, print. Optional. |
46-
| | `--no-color` | Disables color output|
47-
| `kernel browser delete <persistent_browser_id>` | - | Deletes the specified persistent browser |
48-
| `kernel help [command]` | - | Displays help information about Kernel commands. |
87+
| | `--version <version>` | Specify a version of the app (default: latest). Optional. |
88+
| | `--follow`, `-f` | Follow logs in real-time (stream continuously). Optional. |
89+
| | `--since <time>`, `-s` | How far back to retrieve logs (e.g., 5m, 1h). Defaults to 5m if not following, 5s if following. Optional. |
90+
| | `--with-timestamps` | Include timestamps in each log line. Optional. |
91+
92+
## Browser Management Commands
93+
94+
| Command | Description |
95+
|---------|-------------|
96+
| `kernel browsers list` | List running or persistent browsers |
97+
| `kernel browsers delete` | Delete a browser. Must specify either `--by-persistent-id` or `--by-id` |
98+
| | `--by-persistent-id <id>` | Delete browser by persistent ID |
99+
| | `--by-id <id>` | Delete browser by session ID |
100+
| | `--yes`, `-y` | Skip confirmation prompt |
101+
| `kernel browsers view` | Get the live view URL for a browser. Must specify either `--by-persistent-id` or `--by-id` |
102+
| | `--by-persistent-id <id>` | View browser by persistent ID |
103+
| | `--by-id <id>` | View browser by session ID |
104+
105+
## General Commands
49106

50-
This may not be the full list of available CLI commands. Use `kernel --help` in your command line.
107+
| Command | Description |
108+
|---------|-------------|
109+
| `kernel help [command]` | Displays help information about Kernel commands |

0 commit comments

Comments
 (0)