OpenAgents

Commit

Publish resumable CLI login documentation

0fcbbbb81693 · AtlantisPleb · · parent 348dcc8a1da0 

Publish resumable CLI login documentation

Changelog: Agents can now return a CLI sign-in URL and code immediately, then finish after you approve it in any browser.
Changelog-Category: docs
Changelog-Visibility: public
Changelog
Agents can now return a CLI sign-in URL and code immediately, then finish after you approve it in any browser.
Changelog-Category
docs
Changelog-Visibility
public

Deploy story

What this commit did to the running system — joined from the forge receipt chain, the part a commit page elsewhere cannot show.

Not deployed through the forge lane

No push, promotion, build, or deploy receipt references this commit (receipts are scanned over a bounded recent window). Changes shipped by full node replacement carry their proof in the release gate receipt instead.

Changed files

  • modified docs/openagents-cli/command-reference.md
  • modified docs/openagents-cli/import-github.md
  • modified docs/openagents-cli/install.md
  • modified priv/docs/api-tokens.md
  • modified priv/docs/cli-command-reference.md
  • modified priv/docs/import-github.md
  • modified priv/docs/install-cli.md
  • modified priv/docs/signing-in.md
  • modified test/openagents_web/docs_catalog_test.exs

Diff

9 files changed, +142 -39

docs/openagents-cli/command-reference.md modified +17 -6

@@ -38,6 +38,8 @@ Setting `NO_COLOR` also disables ANSI output.

38 38 
| Command | Description |
39 39 
| --- | --- |
40 40 
| `openagents auth login` | Start browser-assisted device authorization and store the token. |
41 
| `openagents auth login --headless` | Return an authorization URL, user code, and resume command without waiting. |
42 
| `openagents auth login --resume` | Complete the pending device authorization after approval. |
41 43 
| `openagents auth login --token-stdin` | Read and store a token from standard input. |
42 44 
| `openagents auth token-stdin` | Read and store a token from standard input. |
43 45 
| `openagents auth status` | Show the selected API, account, namespaces, expiry, and helper state. |

@@ -119,13 +121,22 @@ With `--json`, stdout contains machine-readable output. Human progress and

119 121 
errors do not contaminate a successful JSON response. Responses never include
120 122 
an API token or token digest.
121 123
122 
In a noninteractive process:
124 
In a noninteractive process, `auth login` returns the authorization URL, user
125 
code, and resume command immediately. Surface the URL and code to the user.
126 
After approval, run `auth login --resume`. Use `--headless` to select the same
127 
behavior in a terminal.
123 128
124 
- Set `OPENAGENTS_TOKEN` or provide an existing credential-store entry.
125 
- Pass every ambiguous value as an argument or flag.
126 
- Do not use browser login or global Git-helper setup.
127 
- Handle `SIGINT` and `SIGTERM` as exit code `130`. The CLI cancels in-flight
128 
  HTTP work and terminates its child Git process.
129 
```sh
130 
openagents --json auth login
131 
openagents --json auth login --resume
132 
```
133
134 
You can also set `OPENAGENTS_TOKEN` to an `oa_pat_` user token or provide an
135 
existing credential-store entry. Repository endpoints do not accept
136 
`OPENAGENTS_AGENT_TOKEN`. Pass every ambiguous value as an argument or flag.
137 
Do not use global Git-helper setup in a noninteractive process. Handle
138 
`SIGINT` and `SIGTERM` as exit code `130`; the CLI cancels in-flight HTTP work
139 
and terminates its child Git process.
129 140
130 141 
## Exit codes
131 142
docs/openagents-cli/import-github.md modified +13 -7

@@ -75,18 +75,24 @@ npx --yes @openagentsinc/cli@latest repo import OWNER/REPOSITORY

75 75 
Pin the package version for a reproducible qualification run:
76 76
77 77 
```sh
78 
npx --yes @openagentsinc/cli@0.1.3 \
78 
npx --yes @openagentsinc/cli@0.1.4 \
79 79 
  --profile staging \
80 80 
  repo import OWNER/REPOSITORY \
81 81 
  --private \
82 82 
  --wait-timeout 300
83 83 
```
84 84
85 
In a headless agent process, `auth login` prints the complete approval URL and
86 
user code, then waits. The agent can surface both values while you approve the
87 
request in any browser. Install the CLI globally before you run
88 
`auth setup-git`; a saved Git helper cannot call the temporary executable after
89 
`npx` exits.
85 
In a headless agent process, start the resumable login before the import:
86
87 
```sh
88 
npx --yes @openagentsinc/cli@latest --json auth login
89 
# The agent shows you the URL and code. After you approve the request:
90 
npx --yes @openagentsinc/cli@latest --json auth login --resume
91 
```
92
93 
The first command returns immediately, so the agent does not need streaming
94 
shell output. Install the CLI globally before you run `auth setup-git`; a saved
95 
Git helper cannot call the temporary executable after `npx` exits.
90 96
91 97 
## Import a large repository
92 98

@@ -125,7 +131,7 @@ pointer files without copying the LFS objects.

125 131 
1. Install the qualified CLI version:
126 132
127 133 
   ```sh
128 
   npm install --global @openagentsinc/cli@0.1.0
134 
   npm install --global @openagentsinc/cli@0.1.4
129 135 
   ```
130 136
131 137 
2. Sign in to production and confirm the selected account:
docs/openagents-cli/install.md modified +35 -9

@@ -35,7 +35,7 @@ npx --yes @openagentsinc/cli@latest repo list

35 35 
Pin a version for a reproducible run:
36 36
37 37 
```sh
38 
npx --yes @openagentsinc/cli@0.1.3 --version
38 
npx --yes @openagentsinc/cli@0.1.4 --version
39 39 
```
40 40
41 41 
Place all CLI arguments after the package name:

@@ -67,15 +67,37 @@ Start the browser-assisted device authorization flow:

67 67 
openagents auth login
68 68 
```
69 69
70 
The CLI prints a verification URL and user code, opens the URL when your
71 
operating system supports it, and waits for approval. Complete the flow with
72 
the GitHub account connected to OpenAgents.
70 
In an interactive terminal, the CLI prints a verification URL and user code,
71 
opens the URL when your operating system supports it, and waits for approval.
72 
Complete the flow with the GitHub account connected to OpenAgents. If the
73 
browser does not open, use the printed URL.
73 74
74 
In a headless or noninteractive agent process, the command prints the complete
75 
authorization URL and user code to standard error and waits. Have the agent
76 
surface both values to you. Open the URL in any browser, review the request,
77 
and approve it. The waiting command then stores the OpenAgents token and
78 
continues; the agent never receives your GitHub token.
75 
In a headless or noninteractive agent process, the command returns immediately
76 
with the complete authorization URL, user code, and resume command. This
77 
behavior works with shell tools that do not stream command output. Have the
78 
agent surface the URL and code to you. After you approve the request in any
79 
browser, have the agent run:
80
81 
```sh
82 
openagents auth login --resume
83 
```
84
85 
Use `--headless` to force the resumable flow in an interactive terminal. Use
86 
`openagents --json auth login` and `openagents --json auth login --resume`
87 
when an agent needs structured output. The agent never receives your GitHub
88 
token or the issued OpenAgents token.
89
90 
The two-step flow also works without a global installation:
91
92 
```sh
93 
npx --yes @openagentsinc/cli@latest --json auth login
94 
# After approval:
95 
npx --yes @openagentsinc/cli@latest --json auth login --resume
96 
```
97
98 
The CLI stores the pending request in a private mode-`0600` local file. It
99 
removes the request after successful authorization or when it detects that the
100 
request expired.
79 101
80 102 
The CLI stores the resulting `oa_pat_` token for the selected API origin:
81 103

@@ -114,6 +136,10 @@ For an agent or CI process, set the token in the environment for the process:

114 136 
OPENAGENTS_TOKEN="oa_pat_..." openagents --json repo list
115 137 
```
116 138
139 
`OPENAGENTS_TOKEN` must contain an OpenAgents user token that starts with
140 
`oa_pat_`. `OPENAGENTS_AGENT_TOKEN` is an internal agent-runtime credential.
141 
Repository endpoints do not accept it.
142
117 143 
Do not put a token in a Git URL, configuration file, shell history, or process
118 144 
argument.
119 145
priv/docs/api-tokens.md modified +4

@@ -8,6 +8,10 @@ device authorization and stores it in the operating-system credential store.

8 8 
See [Install the CLI](/docs/install-cli) when you do not need to create a token
9 9 
manually.
10 10
11 
`OPENAGENTS_TOKEN` must contain an OpenAgents user token that starts with
12 
`oa_pat_`. `OPENAGENTS_AGENT_TOKEN` is for an internal agent runtime and does
13 
not authenticate repository API or Git operations.
14
11 15 
## Creating a token
12 16
13 17 
Create a token and copy it immediately. Only a hash is stored, so the value
priv/docs/cli-command-reference.md modified +17 -6

@@ -36,6 +36,8 @@ Setting `NO_COLOR` also disables ANSI output.

36 36 
| Command | Description |
37 37 
| --- | --- |
38 38 
| `openagents auth login` | Start browser-assisted device authorization and store the token. |
39 
| `openagents auth login --headless` | Return an authorization URL, user code, and resume command without waiting. |
40 
| `openagents auth login --resume` | Complete the pending device authorization after approval. |
39 41 
| `openagents auth login --token-stdin` | Read and store a token from standard input. |
40 42 
| `openagents auth token-stdin` | Read and store a token from standard input. |
41 43 
| `openagents auth status` | Show the selected API, account, namespaces, expiry, and helper state. |

@@ -119,13 +121,22 @@ With `--json`, stdout contains machine-readable output. Human progress and

119 121 
errors do not contaminate a successful JSON response. Responses never include
120 122 
an API token or token digest.
121 123
122 
In a noninteractive process:
124 
In a noninteractive process, `auth login` returns the authorization URL, user
125 
code, and resume command immediately. Surface the URL and code to the user.
126 
After approval, run `auth login --resume`. Use `--headless` to select the same
127 
behavior in a terminal.
123 128
124 
- Set `OPENAGENTS_TOKEN` or provide an existing credential-store entry.
125 
- Pass every ambiguous value as an argument or flag.
126 
- Do not use browser login or global Git-helper setup.
127 
- Handle `SIGINT` and `SIGTERM` as exit code `130`. The CLI cancels in-flight
128 
  HTTP work and terminates its child Git process.
129 
```sh
130 
openagents --json auth login
131 
openagents --json auth login --resume
132 
```
133
134 
You can also set `OPENAGENTS_TOKEN` to an `oa_pat_` user token or provide an
135 
existing credential-store entry. Repository endpoints do not accept
136 
`OPENAGENTS_AGENT_TOKEN`. Pass every ambiguous value as an argument or flag.
137 
Do not use global Git-helper setup in a noninteractive process. Handle
138 
`SIGINT` and `SIGTERM` as exit code `130`; the CLI cancels in-flight HTTP work
139 
and terminates its child Git process.
129 140
130 141 
## Handle exit codes
131 142
priv/docs/import-github.md modified +12 -1

@@ -78,7 +78,7 @@ npx --yes @openagentsinc/cli@latest repo import OWNER/REPOSITORY

78 78 
Pin the package version for a reproducible qualification run:
79 79
80 80 
```sh
81 
npx --yes @openagentsinc/cli@0.1.3 \
81 
npx --yes @openagentsinc/cli@0.1.4 \
82 82 
  --profile staging \
83 83 
  repo import OWNER/REPOSITORY \
84 84 
  --private \

@@ -89,6 +89,17 @@ You can use `npx` for the import and the CLI-managed clone. Install the CLI

89 89 
globally before you run `auth setup-git`, because a persistent Git helper
90 90 
cannot call the temporary executable after `npx` exits.
91 91
92 
In a headless agent process, start the resumable login before the import:
93
94 
```sh
95 
npx --yes @openagentsinc/cli@latest --json auth login
96 
# The agent shows you the URL and code. After you approve the request:
97 
npx --yes @openagentsinc/cli@latest --json auth login --resume
98 
```
99
100 
The first command returns immediately, so the agent does not need streaming
101 
shell output.
102
92 103 
## Import a large repository
93 104
94 105 
OpenAgents keeps large Git bundles on disk and streams them to and from the
priv/docs/install-cli.md modified +35 -9

@@ -34,7 +34,7 @@ Pin the package version when a script or qualification run must be

34 34 
reproducible:
35 35
36 36 
```sh
37 
npx --yes @openagentsinc/cli@0.1.3 --version
37 
npx --yes @openagentsinc/cli@0.1.4 --version
38 38 
```
39 39
40 40 
Place every `openagents` argument after the package name:

@@ -61,15 +61,37 @@ Start the browser-assisted device authorization flow:

61 61 
openagents auth login
62 62 
```
63 63
64 
The CLI prints a verification URL and user code, opens the URL when your
65 
operating system supports it, and waits for approval. Complete the flow with
66 
the GitHub account connected to OpenAgents.
64 
In an interactive terminal, the CLI prints a verification URL and user code,
65 
opens the URL when your operating system supports it, and waits for approval.
66 
Complete the flow with the GitHub account connected to OpenAgents. If the
67 
browser does not open, use the printed URL.
67 68
68 
In a headless or noninteractive agent process, the command prints the complete
69 
authorization URL and user code to standard error and waits. Have the agent
70 
surface both values to you. Open the URL in any browser, review the request,
71 
and approve it. The waiting command then stores the OpenAgents token and
72 
continues; the agent never receives your GitHub token.
69 
In a headless or noninteractive agent process, the command returns immediately
70 
with the complete authorization URL, user code, and resume command. This
71 
behavior works with shell tools that do not stream command output. Have the
72 
agent surface the URL and code to you. After you approve the request in any
73 
browser, have the agent run:
74
75 
```sh
76 
openagents auth login --resume
77 
```
78
79 
Use `--headless` to force the resumable flow in an interactive terminal. Use
80 
`openagents --json auth login` and `openagents --json auth login --resume`
81 
when an agent needs structured output. The agent never receives your GitHub
82 
token or the issued OpenAgents token.
83
84 
The two-step flow also works without a global installation:
85
86 
```sh
87 
npx --yes @openagentsinc/cli@latest --json auth login
88 
# After approval:
89 
npx --yes @openagentsinc/cli@latest --json auth login --resume
90 
```
91
92 
The CLI stores the pending request in a private mode-`0600` local file. It
93 
removes the request after successful authorization or when it detects that the
94 
request expired.
73 95
74 96 
The CLI stores the resulting `oa_pat_` token for the selected API origin:
75 97

@@ -108,6 +130,10 @@ For an agent or CI process, set the token for the process:

108 130 
OPENAGENTS_TOKEN="oa_pat_..." openagents --json repo list
109 131 
```
110 132
133 
`OPENAGENTS_TOKEN` must contain an OpenAgents user token that starts with
134 
`oa_pat_`. `OPENAGENTS_AGENT_TOKEN` is an internal agent-runtime credential.
135 
Repository endpoints do not accept it.
136
111 137 
Do not put a token in a Git URL, configuration file, shell history, or process
112 138 
argument.
113 139
priv/docs/signing-in.md modified +5

@@ -29,3 +29,8 @@ Run `openagents auth login` to start a browser-assisted device flow. You review

29 29 
and approve that request while signed in to the site. The CLI receives an
30 30 
OpenAgents API token, not your GitHub token. See [Install the
31 31 
CLI](/docs/install-cli) for npm and `npx` instructions.
32
33 
In a headless process, the command returns the authorization URL and user code
34 
immediately. After you approve the request, the agent runs `openagents auth
35 
login --resume`. The agent never receives your GitHub credential or the issued
36 
OpenAgents token.
test/openagents_web/docs_catalog_test.exs modified +4 -1

@@ -70,10 +70,13 @@ defmodule OpenAgentsWeb.DocsCatalogTest do

70 70 
    end
71 71 
  end
72 72
73 
  test "published CLI docs cover npm, npx, imports, and persistent Git authentication" do
73 
  test "published CLI docs cover agent login, npm, npx, imports, and persistent Git authentication" do
74 74 
    assert {:ok, install} = DocsCatalog.render("install-cli")
75 75 
    assert install.markdown =~ "npm install --global @openagentsinc/cli"
76 76 
    assert install.markdown =~ "npx --yes @openagentsinc/cli@latest"
77 
    assert install.markdown =~ "openagents auth login --resume"
78 
    assert install.markdown =~ "returns immediately"
79 
    assert install.markdown =~ "`OPENAGENTS_AGENT_TOKEN` is an internal agent-runtime credential"
77 80 
    assert install.markdown =~ "Do not run `auth setup-git` through `npx`"
78 81
79 82 
    assert {:ok, import} = DocsCatalog.render("import-github")

This page updates live while a promote is in flight · changelog