@uknows/setup 0.1.0 → 0.2.0

package/lib/check.mjs

@@ -12,7 +12,7 @@ import { randomBytes } from 'node:crypto'
 import { readFileSync } from 'node:fs'
 import http from 'node:http'
 import https from 'node:https'
-import { BASH_STEP, CLI, KEY_CHECK, KEY_PROMPT, SECRET, TROUBLESHOOTING } from './contract.mjs'
+import { CHECK_NETWORK, CLI, KEY_CHECK, SECRET, SETUP_NEXT, TROUBLESHOOTING, keyCheckLine } from './contract.mjs'
 import { ingestEndpoint, sameUknows, siteUrl } from './endpoint.mjs'
 
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
@@ -22,18 +22,66 @@ const ACCEPTED = 'UKNOWS accepted 1 test span.'
 /** What each refusal of the ping route means, from the docs list ("ingest_key_invalid" and so on). */
 const MEANING = new Map(KEY_CHECK.answers.map((a) => [/^[a-z_]+$/.test(a.answer) ? a.answer : null, a.meaning]).filter(([code]) => code))
 
+/** The key variable of apps that keep their own metrics and logs. check reads it when OTEL_EXPORTER_OTLP_HEADERS is not set. */
+const TRACES_HEADERS = 'OTEL_EXPORTER_OTLP_TRACES_HEADERS'
+
+/** A timeout gets 1 more try, for this many times as long: UKNOWS can take about 16 seconds to answer after a quiet time. */
+const RETRY_FACTOR = 3
+
 /**
- * Check the key in OTEL_EXPORTER_OTLP_HEADERS from env (or options.headers), then send 1 test span.
- * @param {{env?: Record<string, string|undefined>, headers?: string, timeoutMs?: number}} [options]
+ * A new key: one that UKNOWS made a moment ago. That is the key of the sign-in of this run, or a key that the site says
+ * is under 5 minutes old (createdAt in its answer). The site knows a new key at once. The data intake (the ingest
+ * address) learns new keys by itself, about every 30 seconds (the key sync of its gateway; measured 26 Oct 2026: about
+ * 30 seconds). So for a new key, a 401 means "not ready yet": the check asks again, every 5 seconds for the first 30
+ * seconds and then every 10 seconds, for up to 2 minutes, with 1 line that says so. A pasted or older key gets 1 try.
+ */
+export const NEW_KEY = {
+  waitMs: 120000, fastMs: 30000, fastEveryMs: 5000, everyMs: 10000, youngMs: 300000,
+  /** The line while the check waits. On a terminal, the time since the wait began follows it, for example 0:35. */
+  waiting: 'UKNOWS is getting your new key ready on the data intake...',
+  /** The same in a pipe or a log, printed once. */
+  waitingPlain: 'UKNOWS is getting your new key ready on the data intake. This can take up to 2 minutes.',
+  ready: (took) => `Your new key is ready on the data intake. It took ${took}.`,
+  /** After 2 minutes. where: " for Your Company, environment Production" when the site named them, else "". */
+  late: (where, siteKnows) => (siteKnows
+    ? `UKNOWS made your new key${where}, but its data intake did not take the key within 2 minutes. This is on the UKNOWS side, not in your app.`
+    : 'UKNOWS did not get your new key ready within 2 minutes. This is on the UKNOWS side, not in your app.'),
+  /** The last line after that: of a run with 1 Yes, of the key command, and of a run that changed the files already. */
+  again: 'Run npx @uknows/setup again in a few minutes. Nothing changed.',
+  againKey: 'Run npx @uknows/setup key again in a few minutes. Nothing changed.',
+  againFiles: 'Next: in a few minutes, run npx @uknows/setup key. It signs you in again, checks the new key and stores it.',
+}
+
+/** Time as the person reads it: 35 seconds, 1 minute 5 seconds, 2 minutes. */
+export function duration(ms) {
+  const s = Math.max(0, Math.round(ms / 1000)), m = Math.floor(s / 60), rest = s % 60
+  const part = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
+  return m ? `${part(m, 'minute')}${rest ? ` ${part(rest, 'second')}` : ''}` : part(rest, 'second')
+}
+
+/** The clock of a real check. Tests pass one whose time moves only when something sleeps. */
+const SYSTEM_CLOCK = { now: () => Date.now(), sleep: (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms))) }
+
+/**
+ * Check the key in OTEL_EXPORTER_OTLP_HEADERS (or OTEL_EXPORTER_OTLP_TRACES_HEADERS) from env, or options.headers,
+ * then send 1 test span. serviceName: the name of the service that setup found, for the test span. A request with no
+ * answer in timeoutMs is tried once more, for up to 3 times as long. onRetry(line) gets 1 line that says so, before it.
+ * newKey: the key came from the sign-in of this run, so a 401 waits for it (NEW_KEY), with clock (now and sleep).
+ * onWait() is called once, when that wait begins. It returns end(line): line is NEW_KEY.ready when the key works after
+ * the wait, else null. A new key that still gets 401 after 2 minutes gives notReady: true and the NEW_KEY.late line.
+ * @param {{env?: Record<string, string|undefined>, headers?: string, timeoutMs?: number, serviceName?: string|null,
+ *   onRetry?: (line: string) => void, newKey?: boolean, clock?: {now: () => number, sleep: (ms: number) => Promise<void>},
+ *   onWait?: () => ((line: string|null) => void)}} [options]
  * @returns {Promise<import('./types.mjs').CheckResult>}
  */
 export async function runCheck(options = {}) {
-  const { env = process.env, timeoutMs = 10000 } = options
-  const raw = options.headers ?? env[SECRET.name]
+  const { env = process.env, timeoutMs = 10000, onRetry = () => {}, clock = SYSTEM_CLOCK, onWait = () => () => {} } = options
+  const ask = (url, method, headers, body) => requestWithRetry(url, method, headers, body, timeoutMs, onRetry)
+  const raw = options.headers ?? (env[SECRET.name]?.trim() ? env[SECRET.name] : env[TRACES_HEADERS])
   if (!raw || !raw.trim()) {
-    return result(2, null, [`${SECRET.name} is not set in this terminal.`, BASH_STEP,
-      'Run these 3 lines. Paste your key when it asks. The key does not show on the screen.',
-      `  ${KEY_PROMPT}`, `  export ${SECRET.name}="${SECRET.header}=$UKNOWS_KEY"`, '  npx @uknows/setup check'])
+    // 1 line, safe to paste at once: read takes the key from the next line, and nothing stays set in the terminal.
+    const vars = [CLI.siteEnv, CLI.endpointEnv].filter((name) => env[name]).map((name) => `${name}=${env[name]}`)
+    return result(2, null, [`${SECRET.name} is not set in this terminal.`, SETUP_NEXT.skipped, `  ${keyCheckLine(vars)}`, CHECK_NETWORK.where])
   }
   const headers = parseHeaders(raw)
   // Hide each header value as written and as decoded. A part without '=' may be a bare key: hide it whole.
@@ -47,22 +95,51 @@ export async function runCheck(options = {}) {
   const site = siteUrl(env)
   if (!site) return result(1, null, [`${CLI.siteEnv} must be an https address with no path, for example https://uknows.example.com.`])
 
-  // 1. Which workspace and environment the key sends to.
   let ping = null
   const lines = [], after = []
+  // A new key waits while UKNOWS gets it ready (NEW_KEY): 1 wait for both steps, with 1 line.
+  const wait = waiter(clock, onWait)
+  let fresh = Boolean(options.newKey)
+  const late = (siteKnows) => {
+    wait.end(null)
+    const where = ping?.workspace ? ` for ${ping.workspace}${ping.environment ? `, environment ${ping.environment}` : ''}` : ''
+    return { ...result(1, 401, [NEW_KEY.late(where, siteKnows)]), ...named(ping), notReady: true }
+  }
+
+  // 1. Which workspace and environment the key sends to.
   if (sameUknows(env)) {
-    const answer = await request(new URL(`${site}${CLI.pingPath}`), 'GET', { [SECRET.header]: headers[keyName] }, null, timeoutMs)
-    ping = explainPing(answer, site, redact)
-    if (ping.stop) return { ...result(1, answer.status ?? null, ping.lines), keyState: ping.keyState ?? null }
+    const pingUrl = new URL(`${site}${CLI.pingPath}`)
+    const askPing = () => ask(pingUrl, 'GET', { [SECRET.header]: headers[keyName] }, null)
+    let answer = await askPing()
+    // A key the site does not know yet. Revoked, paused and the other answers are no wait.
+    const unknown = (a) => a.status === 401 && parse(a.body)?.error === 'ingest_key_invalid'
+    while (fresh && unknown(answer) && await wait.more()) answer = await askPing()
+    if (fresh && unknown(answer)) return late(false)
+    ping = explainPing(answer, site, redact, clock.now())
+    if (ping.stop) {
+      wait.end(null)
+      return { ...result(1, answer.status ?? null, ping.lines), keyState: ping.keyState ?? null }
+    }
     lines.push(...ping.lines)
+    fresh ||= typeof ping.ageMs === 'number' && ping.ageMs < NEW_KEY.youngMs
   } else {
     after.push(`To also see which workspace the key sends to, set ${CLI.siteEnv} with ${CLI.endpointEnv}.`)
   }
 
-  // 2. 1 test span to the ingest address.
+  // 2. 1 test span to the ingest address. A new key that the data intake does not know yet gets 401 there.
   const url = new URL(`${endpoint}/v1/traces`)
-  const response = await request(url, 'POST', { ...headers, 'content-type': 'application/json' }, testSpan(env), timeoutMs)
-  if (response.error) return { ...result(1, null, [...lines, ...explainNetworkError(response.error, url, timeoutMs, env).map(redact), ...after]), ...named(ping) }
+  const send = () => ask(url, 'POST', { ...headers, 'content-type': 'application/json' }, testSpan(env, options.serviceName))
+  let response = await send()
+  while (fresh && response.status === 401 && await wait.more()) response = await send()
+  if (fresh && response.status === 401) return late(true)
+  wait.end(wait.started && response.status >= 200 && response.status < 300 ? NEW_KEY.ready(duration(wait.elapsed())) : null)
+  if (response.error) {
+    // The site said the key works, but the upload to the ingest address failed: say both plainly, with the next step.
+    // After a second timeout, the advice names the longer wait.
+    const keyFine = Boolean(ping?.workspace) && !CERT.test(response.error?.code ?? '')
+    const waited = timedOut(response.error) ? timeoutMs * RETRY_FACTOR : timeoutMs
+    return { ...result(1, null, [...lines, ...(keyFine ? [CHECK_NETWORK.keyFine] : []), ...explainNetworkError(response.error, url, waited, env).map(redact), ...after]), ...named(ping) }
+  }
   const sent = explainResponse(response, redact)
   // Without the site's answer, the accepted span is what shows that the key works.
   const spanLines = sent.lines.map((line) => (line === ACCEPTED && !ping?.workspace ? `${ACCEPTED} Your key works.` : line))
@@ -74,8 +151,11 @@ function named(ping, sent = {}) {
   return { workspace: sent.workspace ?? ping?.workspace ?? null, environment: sent.environment ?? ping?.environment ?? null, keyState: ping?.keyState ?? null }
 }
 
-/** What the ping route said. stop: true when the key is refused, so no span is sent. */
-export function explainPing({ status, error, body }, site, redact = (x) => x) {
+/**
+ * What the ping route said. stop: true when the key is refused, so no span is sent. ageMs: how old the key is, when
+ * the answer says when it was made (createdAt), measured at now. null when it does not say.
+ */
+export function explainPing({ status, error, body }, site, redact = (x) => x, now = Date.now()) {
   const host = new URL(site).hostname
   if (error) return { stop: false, lines: [`Could not ask ${host} which workspace the key sends to (${error.code || 'network error'}). Sending the test span anyway.`] }
   const data = parse(body)
@@ -85,7 +165,8 @@ export function explainPing({ status, error, body }, site, redact = (x) => x) {
     const lines = [`Your key works. It sends data to ${workspace}${environment ? `, environment ${environment}` : ''}.`]
     if (data.keyState === 'retiring') lines.push(`A new key replaced this key. It stops working${data.retiresAt ? ` at ${clean(String(data.retiresAt), redact)}` : ' soon'}. Set the new key.`)
     if (data.status === 'paused') lines.push('Your workspace is paused.')
-    return { stop: false, workspace, environment, keyState: clean(data.keyState, redact), lines }
+    const made = typeof data.createdAt === 'string' ? Date.parse(data.createdAt) : NaN
+    return { stop: false, workspace, environment, keyState: clean(data.keyState, redact), ageMs: Number.isFinite(made) ? Math.max(0, now - made) : null, lines }
   }
   const code = typeof data?.error === 'string' ? data.error : null
   if ((status === 401 || status === 403) && code) {
@@ -108,30 +189,45 @@ export function parseHeaders(value) {
   return out
 }
 
-/** What to print for a network error. Exported for tests: DNS and TLS failures are hard to cause offline. */
+/**
+ * What to print for a network error: what failed, with the host and port, and what to do. The same words as the
+ * answers in "Check your key" (CHECK_NETWORK). Exported for tests: DNS and TLS failures are hard to cause offline.
+ */
 export function explainNetworkError(error, url, timeoutMs, env = {}) {
   const code = error?.code ?? ''
   const port = url.port || (url.protocol === 'https:' ? '443' : '80')
   const host = url.hostname
   const proxy = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy'].some((k) => env[k])
   if (CERT.test(code)) return [`Cannot check the TLS certificate of ${host} (${code}).`, 'A proxy may be in the way. This tool does not use HTTPS_PROXY.']
+  if (/^ERR_INVALID_(?:CHAR|HTTP_TOKEN)/.test(code)) return [`${SECRET.name} has a character that is not allowed in a header.`]
   const seconds = Math.round(timeoutMs / 100) / 10
-  const lines = [
-    code === 'ENOTFOUND' || code === 'EAI_AGAIN' ? `Cannot find ${host}. Check DNS.`
-      : code === 'ECONNREFUSED' ? `${host} refused the connection on port ${port}.`
-      : code === 'UKNOWS_TIMEOUT' || code === 'ETIMEDOUT' ? `No answer in ${seconds} ${seconds === 1 ? 'second' : 'seconds'}.`
-      : code === 'ECONNRESET' || code === 'EPIPE' ? `The connection to ${host} closed before UKNOWS answered.`
-      : code === 'EHOSTUNREACH' || code === 'ENETUNREACH' ? `Cannot reach ${host}. Check your network.`
-      : /^ERR_INVALID_(?:CHAR|HTTP_TOKEN)/.test(code) ? `${SECRET.name} has a character that is not allowed in a header.`
-      : `Cannot reach ${host} (${code || 'unknown error'}).`,
-  ]
-  if (proxy) lines.push('This tool does not use HTTPS_PROXY. Run the check on a network that can reach UKNOWS directly.')
+  const values = { host, port, seconds: seconds === 1 ? '1' : String(seconds), code: code || 'unknown error' }
+  const fill = (t) => t.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+  const dns = code === 'ENOTFOUND' || code === 'EAI_AGAIN'
+  const what = dns ? CHECK_NETWORK.dns : code === 'ECONNREFUSED' ? CHECK_NETWORK.refused
+    : code === 'UKNOWS_TIMEOUT' || code === 'ETIMEDOUT' ? CHECK_NETWORK.timeout.replace('{seconds} seconds', seconds === 1 ? '1 second' : '{seconds} seconds')
+      : code === 'ECONNRESET' || code === 'EPIPE' ? CHECK_NETWORK.reset
+        : code === 'EHOSTUNREACH' || code === 'ENETUNREACH' ? CHECK_NETWORK.unreachable : CHECK_NETWORK.other
+  const lines = [fill(what), ...(dns ? [] : [fill(CHECK_NETWORK.ask)]), CHECK_NETWORK.where]
+  if (proxy) lines.push(CHECK_NETWORK.proxy)
   return lines
 }
 
 // --- request and response ---------------------------------------------------------
 
-function request(url, method, headers, body, timeoutMs) {
+const timedOut = (error) => error?.code === 'UKNOWS_TIMEOUT' || error?.code === 'ETIMEDOUT'
+const secondsOf = (ms) => { const s = Math.round(ms / 100) / 10; return s === 1 ? '1 second' : `${s} seconds` }
+
+/** 1 request. With no answer in timeoutMs, 1 more try for up to RETRY_FACTOR times as long, after 1 line to onRetry. */
+async function requestWithRetry(url, method, headers, body, timeoutMs, onRetry) {
+  const first = await request(url, method, headers, body, timeoutMs)
+  if (!timedOut(first.error)) return first
+  onRetry(`No answer from ${url.hostname} in ${secondsOf(timeoutMs)}. Trying again, for up to ${secondsOf(timeoutMs * RETRY_FACTOR)}.`)
+  return request(url, method, headers, body, timeoutMs * RETRY_FACTOR)
+}
+
+/** 1 HTTP request with node:http or node:https. Resolves {status, headers, body} or {error}. Never rejects. */
+export function request(url, method, headers, body, timeoutMs) {
   return new Promise((resolve) => {
     let done = false, timer = null, req
     const finish = (value) => { if (!done) { done = true; clearTimeout(timer); resolve(value) } }
@@ -165,7 +261,7 @@ function explainResponse({ status, headers, body }, redact) {
   }
   const steps = (id) => TROUBLESHOOTING.find((t) => t.id === id)?.steps ?? []
   if (status === 401) return result(1, status, [`UKNOWS did not accept the key (status 401).`, ...steps('unauthorized')])
-  if (status === 403) return result(1, status, [`UKNOWS refused the key (status 403).`, ...steps('forbidden')])
+  if (status === 403) return result(1, status, [`UKNOWS refused the data (status 403). ${TROUBLESHOOTING.find((t) => t.id === 'forbidden')?.cause ?? ''}`.trim(), ...steps('forbidden')])
   const textual = !data && /json|text/i.test(String(headers['content-type'] ?? ''))
   const message = clean(typeof data?.message === 'string' ? data.message : textual ? body : null, redact)
   const lines = [`UKNOWS answered with status ${status}.`]
@@ -175,11 +271,11 @@ function explainResponse({ status, headers, body }, redact) {
 }
 
 /** 1 span in OTLP/JSON: hex ids, integer enums, int64 values as decimal strings. */
-function testSpan(env) {
+function testSpan(env, serviceName = null) {
   const hex = (bytes) => { let id; do id = randomBytes(bytes).toString('hex'); while (/^0+$/.test(id)); return id }
   const start = BigInt(Date.now()) * 1000000n
   return JSON.stringify({ resourceSpans: [{
-    resource: { attributes: [{ key: 'service.name', value: { stringValue: env.OTEL_SERVICE_NAME || 'uknows-setup-check' } }] },
+    resource: { attributes: [{ key: 'service.name', value: { stringValue: env.OTEL_SERVICE_NAME || serviceName || 'uknows-setup-check' } }] },
     scopeSpans: [{ scope: { name: '@uknows/setup', version: VERSION }, spans: [{
       traceId: hex(16), spanId: hex(8), name: 'uknows setup check', kind: 1,
       startTimeUnixNano: String(start), endTimeUnixNano: String(start + 1000000n),
@@ -190,6 +286,26 @@ function testSpan(env) {
 
 // --- helpers ------------------------------------------------------------------------
 
+/**
+ * The wait for a new key (NEW_KEY). more() starts it at the first call (onWait() shows its line), sleeps until the next
+ * try, and is false once 2 minutes have passed since the start. end(line) ends the line once, with line or nothing.
+ */
+function waiter(clock, onWait) {
+  let started = null, finish = null
+  return {
+    get started() { return started !== null },
+    elapsed: () => (started === null ? 0 : clock.now() - started),
+    async more() {
+      if (started === null) { started = clock.now(); finish = onWait() ?? (() => {}) }
+      const waited = clock.now() - started
+      if (waited >= NEW_KEY.waitMs) return false
+      await clock.sleep(Math.min(waited < NEW_KEY.fastMs ? NEW_KEY.fastEveryMs : NEW_KEY.everyMs, NEW_KEY.waitMs - waited))
+      return true
+    },
+    end(line) { if (finish) { const done = finish; finish = null; done(line) } },
+  }
+}
+
 function result(exit, status, lines) {
   return { ok: false, status, workspace: null, environment: null, lines, exit }
 }

package/lib/ci.mjs

@@ -0,0 +1,21 @@
+/*
+ * Does this run in a pipeline? Setup and remove change a repo once, on a
+ * computer, so in a pipeline they stop with exit 2 unless --allow-ci is set.
+ * The variables come from contract.mjs CLI.ciEnv.
+ */
+import { CLI } from './contract.mjs'
+
+/**
+ * The name of the first CI variable that is set, or null. CI counts when it is not empty, 0 or false.
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function ciVariable(env = {}) {
+  for (const name of CLI.ciEnv) {
+    const value = String(env[name] ?? '').trim()
+    if (!value) continue
+    if (name === 'CI' && /^(?:0|false)$/i.test(value)) continue
+    return name
+  }
+  return null
+}

package/lib/cli.mjs

@@ -5,59 +5,117 @@
 import { statSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { runCheck } from './check.mjs'
-import { CLI, DOCS_URL, INGEST_ENDPOINT, SECRET, SITE_URL } from './contract.mjs'
+import { CI_CD, CLI, DEFAULT_AGENT_REGISTRY, DOCS_URL, SECRET, SETUP_NEEDS } from './contract.mjs'
 import { toServiceName } from './detect.mjs'
-import { ingestEndpoint, siteUrl } from './endpoint.mjs'
-import { runRemove, runSetup } from './engine.mjs'
-import { TOOL, VERSION } from './manifest.mjs'
+import { ingestEndpoint, siteUrl, validAppUrl } from './endpoint.mjs'
+import { CHANNELS, validRegistry } from './stacks/channel.mjs'
+import { UPDATE_BOTS } from './updates.mjs'
+import { runKey, runRemove, runSetup } from './engine.mjs'
+import { TOOL, VERSION, readManifest } from './manifest.mjs'
 import { UsageError, createUI } from './ui.mjs'
 
-const FLAGS = { '--dry-run': 'dryRun', '--yes': 'yes', '-y': 'yes', '--all': 'all', '--json': 'json', '--force': 'force',
-  '--check': 'check', '--help': 'help', '-h': 'help', '--version': 'version' }
-const VALUES = { '--path': 'path', '--service-name': 'serviceName' }
-const COMMANDS = { setup: ['dryRun', 'yes', 'path', 'all', 'json', 'serviceName', 'force'], remove: ['yes', 'path', 'json', 'force'], check: ['json'] }
+const FLAGS = { '--dry-run': 'dryRun', '--yes': 'yes', '-y': 'yes', '--all': 'all', '--json': 'json', '--force': 'force', '--updates': 'updates',
+  '--allow-ci': 'allowCi', '--check': 'check', '--help': 'help', '-h': 'help', '--version': 'version', '--step-by-step': 'stepByStep', '--paste-key': 'pasteKey',
+  '--functions-opentelemetry': 'functionsOpenTelemetry' }
+const VALUES = { '--path': 'path', '--service-name': 'serviceName', '--channel': 'channel', '--update-bot': 'updateBot' }
+const COMMANDS = { setup: ['dryRun', 'yes', 'path', 'all', 'json', 'serviceName', 'force', 'allowCi', 'stepByStep', 'pasteKey', 'channel', 'updates', 'updateBot', 'functionsOpenTelemetry'], key: ['path', 'pasteKey'],
+  remove: ['yes', 'path', 'json', 'force', 'allowCi'], check: ['json'] }
+/** Flags that only mean something when setup asks questions in a terminal. */
+const ASKS = { stepByStep: '--step-by-step', pasteKey: '--paste-key' }
 
-export const HELP = `uknows-setup adds OpenTelemetry to your app, so it sends traces to UKNOWS.
+export const HELP = `uknows-setup adds OpenTelemetry to your app, so it sends traces and logs to UKNOWS.
 
 Usage:
   npx @uknows/setup [setup] [options]   Find your app, show the plan, then apply it.
+  npx @uknows/setup key [options]       Check and store the key of another environment, for example Production.
   npx @uknows/setup remove [options]    Undo what setup changed.
   npx @uknows/setup check               Send 1 test span with the key in ${SECRET.name}.
 
 Options:
   --dry-run               Show the plan. Change nothing.
   --yes, -y               Apply without asking. Never asks any question.
-  --path <folder>         The folder to set up. The default is this folder.
+  --step-by-step          Ask before each step, instead of 1 question for the whole plan.
+  --paste-key             Paste your key instead of signing in to UKNOWS in your browser.
+  --path <folder>         The folder to set up. The default is this folder. key takes only this option and --paste-key.
   --all                   Set up every service folder. Each one gets its own OTEL_SERVICE_NAME.
   --service-name <name>   The name of the service in UKNOWS.
+  --channel <name>        Java, .NET and Node.js apps with a Dockerfile: copy the UKNOWS agent from the
+                          agent image of a channel, stable or early, at each build. Then a new agent
+                          reaches the app at its next build, with no change to your repo.
+  --update-bot <name>     How the OpenTelemetry packages of your app stay up to date: renovate,
+                          dependabot (GitHub only, with a workflow that merges the updates and starts
+                          the deploy) or none. Without it, setup picks, as below.
+  --functions-opentelemetry
+                          Azure Functions apps: turn on OpenTelemetry in host.json, instead of the UKNOWS hooks
+                          that setup adds when the app sends to Application Insights or it cannot look.
   --json                  Print a JSON report. Without --yes, setup only plans.
   --force                 Run even when the repo has changes that are not committed.
+  --allow-ci              Apply in a pipeline. Only for a bot or an AI agent that opens a pull request.
   --check                 The same as the check command.
   --help, -h              Show this help.
   --version               Show the version.
 
-Exit codes:
-  0  Done, or nothing to do.
-  1  Stopped or failed. Nothing changed.
-  2  Usage error, or you need to pick a service.
-  3  You need to do 1 or more steps by hand.
+Setup keeps the UKNOWS agent up to date by itself, and the plan says how and why:
+  1. Java, .NET and Node.js apps that build from a Dockerfile get the agent channel: each build
+     copies the newest stable agent, so no update pull request is needed.
+  2. Other apps get Renovate when your repo uses Renovate already.
+  3. Else Dependabot on GitHub. On GitLab, Azure DevOps or Bitbucket, setup adds renovate.json
+     and says how to add Renovate in 1 step.
+--update-bot and --channel choose instead.
+
+Run setup once on your computer, not in your pipeline. In a pipeline, setup and remove
+change nothing and exit 2, or exit 0 when the repo is already set up. --dry-run, a --json plan,
+check, --help and --version still work.
+To check in a pipeline that a repo is set up ("status": "nothing-to-change", "exitCode": 0):
+  ${CI_CD.snippet.code}
+
+In a terminal, setup opens your browser so you sign in to UKNOWS and pick the workspace and
+the environment. Your key then comes to setup by itself. Setup checks it, then shows the whole
+plan and asks 1 question: Do all of this? (Y/n). On a yes, it changes the files and also:
+  Stores the key on your platform with az, gh or kubectl, for the environment of the key.
+  Adds the key to a deploy file that would remove it on the next deploy.
+  Creates a branch, commits the files that setup changed, pushes it and opens a pull request.
+To show this plan, it reads your Azure subscriptions, your GitHub repo or your kubectl
+contexts. It changes nothing there until you say yes. With --step-by-step, it asks before each
+of these steps instead, after the change to the files.
+Then it opens the page where you watch your app connect. With --yes or --json, in a pipeline
+or without a terminal, it does none of these and prints the steps for you.
+
+Exit codes of setup and remove (they describe your repo):
+  0  Done, already set up, or nothing to do. Only the key steps on your platform are left.
+     Merging the pull request and deploying are left too.
+  1  Stopped or failed. Nothing changed. For example, no app found or another APM agent.
+     In a terminal, also when UKNOWS refuses the key. With --step-by-step, the changes to your repo stay.
+  2  Needs your input. Nothing changed. For example, pick a service, or a pipeline without --allow-ci.
+  3  Done, but you must do 1 or more steps in your repo before traces flow.
+Ctrl+C while setup waits for your sign-in stops it with exit code 130.
+check exits 0 when UKNOWS takes the test span, 1 when UKNOWS refuses the key or cannot be
+reached, and 2 when ${SECRET.name} is not set.
+key exits 0 when it stored the key or printed its steps, 1 when the folder is not set up or UKNOWS
+refuses the key or cannot be reached, and 2 without a terminal or a key.
+
+You need on this computer (setup updates the lock file of your app with its own tools):
+${SETUP_NEEDS.map((line) => `  ${line}`).join('\n')}
 
 Environment:
   ${SECRET.name}
       Your key, for check, as ${SECRET.value}. Set it only in your terminal.
-  ${CLI.siteEnv}
-      A test UKNOWS site, for check and the docs links. The default is ${SITE_URL}.
-  ${CLI.endpointEnv}
-      A test ingest address, for setup and check. The default is ${INGEST_ENDPOINT}.
+  ${CLI.agentRegistryEnv}
+      Another store of the UKNOWS agent images for the agent channel, as a registry and path, for example
+      registry.example.com/uknows.
 
-After setup, the tool asks for your key to check it. The key does not show on the screen.
-This tool never writes your key to a file.
+In a terminal, the tool gets your key when you sign in, or uses the key in ${SECRET.name}.
+With --paste-key, it asks you to paste it. The key does not show on the screen.
+With --yes in a terminal, it checks the key in ${SECRET.name} if it is set.
+This tool never writes your key to a file. To store it, az, gh and kubectl read it from
+a pipe, so it is in no command line.
 Docs: ${DOCS_URL}
 `
 
-/** @returns {{command: 'setup'|'remove'|'check', dryRun: boolean, yes: boolean, all: boolean, json: boolean, force: boolean, help: boolean, version: boolean, path: string|null, serviceName: string|null}} */
+/** @returns {{command: 'setup'|'key'|'remove'|'check', dryRun: boolean, yes: boolean, all: boolean, json: boolean, force: boolean, allowCi: boolean, help: boolean, version: boolean, path: string|null, serviceName: string|null, stepByStep: boolean, pasteKey: boolean, channel: string|null, updates: boolean, updateBot: string|null}} */
 export function parseArgs(argv) {
-  const opts = { command: null, dryRun: false, yes: false, all: false, json: false, force: false, help: false, version: false, path: null, serviceName: null }
+  const opts = { command: null, dryRun: false, yes: false, all: false, json: false, force: false, allowCi: false, help: false, version: false, path: null, serviceName: null,
+    stepByStep: false, pasteKey: false, channel: null, updates: false, updateBot: null, functionsOpenTelemetry: false }
   const given = []
   let check = false
   for (let i = 0; i < argv.length; i++) {
@@ -87,17 +145,27 @@ export function parseArgs(argv) {
     } else throw new UsageError(`Unknown option: ${flag}.`)
   }
   if (check && opts.command && opts.command !== 'check') throw new UsageError(`--check does not work with ${opts.command}.`)
+  if (opts.channel !== null && !CHANNELS.includes(opts.channel)) throw new UsageError(`--channel is ${CHANNELS.join(' or ')}.`)
+  if (opts.updateBot !== null) {
+    if (!UPDATE_BOTS.includes(opts.updateBot)) throw new UsageError(`--update-bot is ${UPDATE_BOTS.slice(0, -1).join(', ')} or ${UPDATE_BOTS.at(-1)}.`)
+    opts.updates = true
+  }
   opts.command = check ? 'check' : opts.command ?? 'setup'
   for (const [key, flag] of given) {
     if (!COMMANDS[opts.command].includes(key)) throw new UsageError(`${flag} does not work with ${opts.command}.`)
   }
+  // --yes and --json never ask, and a dry run asks for no key: the flags that change the questions do not fit them.
+  for (const [key, flag] of Object.entries(ASKS)) {
+    const other = opts.yes ? '--yes' : opts.json ? '--json' : opts.dryRun && key === 'pasteKey' ? '--dry-run' : null
+    if (opts[key] && other) throw new UsageError(`${flag} does not work with ${other}.`)
+  }
   return opts
 }
 
 /**
  * Run the CLI. Returns the exit code.
  * @param {string[]} argv
- * @param {{stdin?: any, stdout?: any, stderr?: any, cwd?: string, env?: Record<string, string|undefined>, interactive?: boolean, deps?: object}} [io]
+ * @param {{stdin?: any, stdout?: any, stderr?: any, cwd?: string, env?: Record<string, string|undefined>, interactive?: boolean, terminal?: boolean, deps?: object}} [io]
  */
 export async function main(argv, io = {}) {
   const { stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), env = process.env, deps = {} } = io
@@ -116,12 +184,25 @@ export async function main(argv, io = {}) {
   }
   if (args.help) { stdout.write(HELP); return 0 }
   if (args.version) { stdout.write(`${VERSION}\n`); return 0 }
-  if (args.command === 'check') return check(args, { stdout, stderr, env }, deps.runCheck ?? runCheck)
+  if (args.command === 'check') return check(args, { stdout, stderr, env, cwd }, deps.runCheck ?? runCheck)
+  const run = { setup: runSetup, key: runKey, remove: runRemove }[args.command]
 
   // setup writes the same ingest address that check sends to.
   const endpoint = ingestEndpoint(env)
   if (!endpoint) return usage(`${CLI.endpointEnv} must be an https address.`)
   if (!siteUrl(env)) return usage(`${CLI.siteEnv} must be an https address with no path, for example https://uknows.example.com.`)
+  if (!validAppUrl(env)) return usage(`${CLI.appEnv} must be an https address with no path, for example https://app.uknows.example.com.`)
+  // The agent channel: the store of the UKNOWS agent images, UKNOWS_AGENT_REGISTRY or the one of this release.
+  const given = String(env[CLI.agentRegistryEnv] ?? '').trim().replace(/\/+$/, '')
+  if (given && !validRegistry(given)) return usage(`${CLI.agentRegistryEnv} must be the registry and path of the UKNOWS agent images, for example registry.example.com/uknows.`)
+  const registry = given || (validRegistry(DEFAULT_AGENT_REGISTRY) ? DEFAULT_AGENT_REGISTRY : null)
+  let channel = null
+  if (args.channel) {
+    if (!registry) return usage(`--channel needs ${CLI.agentRegistryEnv}: the registry and path of the UKNOWS agent images, for example registry.example.com/uknows.`)
+    channel = { name: args.channel, registry }
+  }
+  // The default (updates.mjs, step 1): the stable channel for the apps that fit, unless --update-bot or --channel chose.
+  const defaultChannel = !args.channel && !args.updateBot && registry ? { name: 'stable', registry } : null
   const root = resolve(cwd, args.path ?? '.')
   let folder = false
   try { folder = statSync(root).isDirectory() } catch { /* missing */ }
@@ -129,9 +210,9 @@ export async function main(argv, io = {}) {
   if (args.serviceName !== null && (deps.toServiceName ?? toServiceName)(args.serviceName) !== args.serviceName) {
     return usage(`${args.serviceName} is not a valid service name. Use lowercase letters, digits and -, up to 63 characters.`)
   }
-  const ui = createUI({ stdin, stdout, stderr, json: args.json, interactive: io.interactive })
+  const ui = createUI({ stdin, stdout, stderr, json: args.json, interactive: io.interactive, terminal: io.terminal, env })
   try {
-    const { code, report } = await (args.command === 'remove' ? runRemove : runSetup)({ ...args, root, endpoint, env }, { ...deps, ui })
+    const { code, report } = await run({ ...args, channel, defaultChannel, root, endpoint, env }, { ...deps, ui })
     if (args.json) stdout.write(`${JSON.stringify(report, null, 2)}\n`)
     return code
   } finally {
@@ -139,8 +220,12 @@ export async function main(argv, io = {}) {
   }
 }
 
-async function check(args, { stdout, stderr, env }, run) {
-  const result = await run({ env })
+async function check(args, { stdout, stderr, env, cwd }, run) {
+  // The test span carries the service name that setup recorded here, so the workspace never lists a made-up app.
+  let serviceName = null
+  try { serviceName = readManifest(cwd)?.services?.[0]?.name ?? null } catch { /* not valid: no name */ }
+  // The retry line goes to stderr, so --json stays 1 JSON document on stdout.
+  const result = await run({ env, serviceName, onRetry: (line) => stderr.write(`${line}\n`) })
   const status = result.exit === 2 ? 'no-key' : result.ok ? 'reached' : result.status === null ? 'network-error' : 'rejected'
   const lines = redact(result.lines, env[SECRET.name])
   if (args.json) {