cueapril 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,17 +9,17 @@ It needs Node.js 20 or later and has no dependencies.
9
9
  Run it without installing:
10
10
 
11
11
  ```sh
12
- npx -y --package=https://app.cueapril.com/downloads/cueapril-cli-1.1.0.tgz cueapril --help
12
+ npx -y cueapril@latest --help
13
13
  ```
14
14
 
15
15
  Or install it once:
16
16
 
17
17
  ```sh
18
- npm install -g https://app.cueapril.com/downloads/cueapril-cli-1.1.0.tgz
18
+ npm install -g cueapril
19
19
  cueapril --help
20
20
  ```
21
21
 
22
- The examples below write `cueapril` for either form. Once the unscoped `cueapril` package is published on npm, `npx -y cueapril@latest`, `pnpm dlx cueapril`, `bunx cueapril` and `yarn dlx cueapril` work too.
22
+ The public npm package is `cueapril`. `pnpm dlx cueapril`, `bunx cueapril` and `yarn dlx cueapril` work too. Python users can use `uvx cueapril init` or `pipx install cueapril`; Python 3.10+ and an installed Node.js 20+ are required. The examples below write `cueapril` for any form. A versioned fallback download is available at https://app.cueapril.com/downloads/cueapril-cli-1.2.0.tgz.
23
23
 
24
24
  ## Set up (an agent can do this itself)
25
25
 
@@ -27,12 +27,21 @@ The examples below write `cueapril` for either form. Once the unscoped `cueapril
27
27
  cueapril init
28
28
  ```
29
29
 
30
+ A coding agent can follow this single prompt:
31
+
32
+ > Install CueApril from the public `cueapril` npm package and connect it to this coding agent. Use `CUEAPRIL_API_KEY` if already supplied. Otherwise run `npx -y cueapril@latest init --no-login --json` and ask me to supply a CueApril API key through a secret manager or secure local input, or offer browser approval with `init --no-wait --no-browser --json`. Never ask me to paste a key into chat. Complete init, run doctor, and report any remaining project setup steps without starting a paid assessment.
33
+
34
+ For an existing key, set `CUEAPRIL_API_KEY` through your secret manager and run `init --no-login --json`, or pipe the secret manager's output into `cueapril init --key-stdin --json`. `--key-stdin` accepts one complete key, verifies read access, then saves it privately. It refuses terminal input and conflicting browser or environment credentials; it never accepts a key as a command-line argument. Add `--dry-run` to verify and preview without saving.
35
+
36
+ For browser approval in a short agent shell, run `cueapril init --no-wait --no-browser --json`. Exit 4 and `login.status: "pending"` mean approval is still required. Give the person `login.verification_url` and `login.code`; after approval execute `login.resume_command` for npm, or `login.resume_commands.pypi` for uvx. The `next_actions` entries include `commands.npm`, `commands.pypi`, `commands.installed` and logical CLI `argv` so agents can reuse their installer. Repeating the pending command reuses the same request. With no key, `init --no-login --json` returns exit 5, `login.status: "auth_required"` and structured `next_actions`; it changes nothing.
37
+
30
38
  `init` gets a key by one browser approval if none is stored: it prints a link and a code, an organisation owner or admin opens the link, checks the code and approves, and the key is saved in your user configuration (`~/.config/cueapril/credentials.json`, mode 0600, never inside a repository, even through a symbolic link). It then checks the project's setup and prints a link for anything a person must do, adds the `cueapril` MCP server to Claude Code, Codex, Gemini CLI and Cursor at user level (backing up any file it edits), and installs the `cueapril-qa` skill. Claude Code's entry is added with `claude mcp add-json` and holds no key: its `headersHelper` reads the key from `~/.config/cueapril/claude-code-headers.json` (mode 0600) each time Claude Code connects. Re-running it changes nothing. Useful flags: `--agents claude,codex`, `--scope project` (installs the skill in this repository), `--dry-run`, `--json`.
31
39
 
32
40
  | Command | What it does |
33
41
  | --- | --- |
34
42
  | `cueapril login [--name <label>] [--no-browser] [--no-wait]` | Only the browser approval, storing the key. `--no-wait` prints the link and returns; the next `login` or `init` resumes the same request. |
35
- | `cueapril doctor [--json]` | Checks the API, the key, readiness, agent configuration and the skill. Exit 0 when nothing fails. |
43
+ | `cueapril login --key-stdin [--json]` | Verifies and privately stores an existing agent key from a pipe. |
44
+ | `cueapril doctor [--project <id>] [--json]` | Checks the API, the key, readiness, agent configuration and the skill. Supply `--project` when the key covers several projects. Exit 0 when nothing fails. |
36
45
  | `cueapril logout [--local]` | Revokes the stored key on CueApril and deletes it here (`--local` only deletes it here). |
37
46
 
38
47
  ## Configure
@@ -42,9 +51,9 @@ cueapril init
42
51
  | `CUEAPRIL_API_KEY` | Agent key, `cueapril_sk_...`, from `cueapril login` or created by an organisation admin in the CueApril web app settings (projects, scopes, expiry and optional spend cap). Falls back to `TENHAW_TOKEN`, then to the key stored by `login` or `init`. |
43
52
  | `CUEAPRIL_URL` | API origin. Default `https://app.cueapril.com`. Falls back to `TENHAW_URL`. |
44
53
 
45
- The key is read from the environment or the user store, sent only as `Authorization: Bearer`, never printed or logged, and never passed on a command line; only `login` and `init` write it, to the user store and user-level agent configuration (files of mode 0600, outside any repository). Keep it in your CI secret store. Starting an assessment needs the `quality:run` scope and cancelling needs `quality:cancel`; reading needs `quality:read`.
54
+ The key is read from the environment, the user store or an explicit `--key-stdin` pipe, sent only as `Authorization: Bearer`, never printed or logged, and never passed on a command line; only `login` and `init` write it, to the user store and user-level agent configuration (files of mode 0600, outside any repository). Keep it in your CI secret store. Starting an assessment needs the `quality:run` scope and cancelling needs `quality:cancel`; reading needs `quality:read`.
46
55
 
47
- The CLI talks only to HTTPS origins (plain HTTP only on `localhost`), refuses redirects, caps response size at 10 MB and identifies itself with `X-CueApril-Client: cli/1.1.0`.
56
+ The CLI talks only to HTTPS origins (plain HTTP only on `localhost`), refuses redirects, caps response size at 10 MB and identifies itself with `X-CueApril-Client: cli/1.2.0`.
48
57
 
49
58
  ## Commands
50
59
 
@@ -63,7 +72,7 @@ The CLI talks only to HTTPS origins (plain HTTP only on `localhost`), refuses re
63
72
 
64
73
  `cueapril <command> --help` shows one command; `cueapril help legacy` lists the older dotted actions.
65
74
 
66
- Every command except `mcp-config` calls `POST <CUEAPRIL_URL>/api/v1/quality/agent-tools/<tool>`, the REST form of the CueApril MCP tools, so the CLI, MCP and REST give the same answers.
75
+ Assessment commands call `POST <CUEAPRIL_URL>/api/v1/quality/agent-tools/<tool>`, the REST form of the CueApril MCP tools, so the CLI, MCP and REST give the same answers. `init`, `login`, `logout` and `doctor` also manage local credentials or client configuration; `mcp-config` only prints configuration.
67
76
 
68
77
  ## Exit codes
69
78
 
@@ -82,7 +91,7 @@ Every command except `mcp-config` calls `POST <CUEAPRIL_URL>/api/v1/quality/agen
82
91
 
83
92
  By default the CLI prints a summary for people: outcome, verdict, gate, task counts, the first failures with expected and observed values, suggested fix locations and a link to the assessment in the web app.
84
93
 
85
- With `--json` it prints exactly one JSON object on stdout, the final tool result plus `"exit_code"`, and nothing else. Errors become `{"error": {"message": ...}, "exit_code": 5}`. Progress and error messages always go to stderr, so `--json` output can be piped straight into `jq` or parsed by an agent.
94
+ Assessment commands with `--json` print exactly one JSON object on stdout, the final tool result plus `"exit_code"`, and nothing else. Errors become `{"error": {"message": ...}, "exit_code": 5}`. `init --json` prints one setup summary with `exit_code` and `next_actions`; device `login --json` prints event JSON lines. Progress and error messages always go to stderr, so output can be parsed by an agent.
86
95
 
87
96
  ### On GitHub
88
97
 
@@ -134,8 +143,7 @@ jobs:
134
143
  env:
135
144
  CUEAPRIL_API_KEY: ${{ secrets.CUEAPRIL_API_KEY }}
136
145
  run: >-
137
- npx -y --package=https://app.cueapril.com/downloads/cueapril-cli-1.1.0.tgz
138
- cueapril assess --pr ${{ github.event.pull_request.number }} --wait --timeout 90
146
+ npx -y cueapril@latest assess --pr ${{ github.event.pull_request.number }} --wait --timeout 90
139
147
  ```
140
148
 
141
149
  Connect an MCP client instead of shelling out:
package/client.mjs CHANGED
@@ -1,15 +1,11 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
 
3
- export const CLI_VERSION = '1.1.0';
3
+ export const CLI_VERSION = '1.2.0';
4
4
  export const CLIENT_IDENTIFIER = `cli/${CLI_VERSION}`;
5
5
  export const USER_AGENT = `cueapril-cli/${CLI_VERSION}`;
6
6
  export const DEFAULT_BASE_URL = 'https://app.cueapril.com';
7
- /**
8
- * How people and agents run this CLI. Until the unscoped `cueapril` npm package is
9
- * published it is installed from the web app's tarball; afterwards this becomes
10
- * 'npx -y cueapril@latest'.
11
- */
12
- export const RUN_COMMAND = `npx -y --package=${DEFAULT_BASE_URL}/downloads/cueapril-cli-${CLI_VERSION}.tgz cueapril`;
7
+ /** The public package-manager entry point for people and coding agents. */
8
+ export const RUN_COMMAND = 'npx -y cueapril@latest';
13
9
  export const AGENT_TOOL_PREFIX = 'cueapril_';
14
10
  /** Older clients called tools with this prefix; the server still accepts it on calls. */
15
11
  export const LEGACY_AGENT_TOOL_PREFIX = 'tenhaw_';
package/commands.mjs CHANGED
@@ -1092,9 +1092,12 @@ Setup (a coding agent can run these itself; a person approves once in the browse
1092
1092
  cueapril init [--agents auto|claude,codex,gemini,cursor] [--scope user|project]
1093
1093
  Get a key by browser approval if none is stored, check readiness, configure Claude Code,
1094
1094
  Codex, Gemini CLI and Cursor at user level, and install the cueapril-qa skill.
1095
+ --no-login --json returns auth_required with next_actions when a key is missing.
1096
+ --key-stdin verifies and stores an existing key from a pipe; --no-wait returns an approval link.
1095
1097
  cueapril login [--name <label>] [--no-browser] [--no-wait]
1096
1098
  Approve an agent key in the browser and store it for this user (never printed).
1097
- cueapril doctor
1099
+ Or use login --key-stdin to import a key from a secret manager's output.
1100
+ cueapril doctor [--project <id>]
1098
1101
  Check the API, the key, readiness, agent configuration and the skill.
1099
1102
  cueapril logout
1100
1103
  Revoke the stored key on CueApril and delete it here.
package/doctor.mjs CHANGED
@@ -10,13 +10,15 @@ import { describeKeySource, maskKey, resolveApiKey } from './key-store.mjs';
10
10
  import { inspectAgents } from './agents.mjs';
11
11
  import { CHECK_SETUP_TOOL, bundledSkillPath, skillTargets, summariseSetup } from './init.mjs';
12
12
 
13
- export const DOCTOR_USAGE = `Usage: cueapril doctor [--json]
13
+ export const DOCTOR_USAGE = `Usage: cueapril doctor [--project <id>] [--json]
14
14
 
15
15
  Checks the CueApril server URL, your key (masked), the API health, whether the
16
16
  key is accepted, which coding agents have a CueApril MCP entry and whether the
17
- cueapril-qa skill is installed. Exit 0 when nothing fails, 5 otherwise.`;
17
+ cueapril-qa skill is installed. Use --project when the key covers several
18
+ projects. Exit 0 when nothing fails, 5 otherwise.`;
18
19
 
19
20
  const INIT_COMMAND = `${RUN_COMMAND} init`;
21
+ const PROJECT_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
20
22
  const LABELS = {
21
23
  server: 'Server',
22
24
  key: 'Key',
@@ -38,15 +40,20 @@ function line(check) {
38
40
  export async function runDoctor(argv = [], deps = {}) {
39
41
  const io = defaultDeps(deps);
40
42
  let flags;
43
+ let projectId;
41
44
  try {
42
45
  ({ values: flags } = parseArgs({
43
46
  args: argv,
44
47
  allowPositionals: false,
45
48
  strict: true,
46
- options: { json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
49
+ options: { json: { type: 'boolean' }, project: { type: 'string' }, help: { type: 'boolean', short: 'h' } },
47
50
  }));
51
+ if (flags.project !== undefined) {
52
+ projectId = String(flags.project).trim();
53
+ if (!PROJECT_ID.test(projectId)) throw new Error('--project must be a CueApril project id.');
54
+ }
48
55
  } catch (error) {
49
- writeLine(io.stderr, `${safeText(error.message)}\n\n${DOCTOR_USAGE}`);
56
+ writeLine(io.stderr, `${safeText(redact(error.message))}\n\n${DOCTOR_USAGE}`);
50
57
  return { exitCode: EXIT.error, report: null };
51
58
  }
52
59
  if (flags.help) {
@@ -111,7 +118,7 @@ export async function runDoctor(argv = [], deps = {}) {
111
118
 
112
119
  if (resolved) {
113
120
  try {
114
- const raw = await client.callTool(CHECK_SETUP_TOOL, {}, resolved.key, { timeoutMs: 30_000 });
121
+ const raw = await client.callTool(CHECK_SETUP_TOOL, projectId ? { project_id: projectId } : {}, resolved.key, { timeoutMs: 30_000 });
115
122
  const setup = summariseSetup(raw, baseUrl);
116
123
  add('key_valid', 'ok', `Accepted${setup.organisation ? ` for ${setup.organisation}` : ''}`);
117
124
  if (setup.ready) {
package/init.mjs CHANGED
@@ -30,7 +30,7 @@ import {
30
30
  import { createHttpClient, resolveBaseUrl } from './http.mjs';
31
31
  import { RUN_COMMAND } from './client.mjs';
32
32
  import { describeKeySource, maskKey, resolveApiKey } from './key-store.mjs';
33
- import { runLogin } from './login.mjs';
33
+ import { importApiKey, runLogin } from './login.mjs';
34
34
  import { AGENT_NAMES, applyAgentChanges, detectAgents, parseAgentList, planAgentChanges } from './agents.mjs';
35
35
 
36
36
  export const CHECK_SETUP_TOOL = 'cueapril_check_setup';
@@ -40,6 +40,7 @@ const PROJECT_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
40
40
 
41
41
  export const INIT_USAGE = `Usage: cueapril init [--agents auto|none|claude,codex,gemini,cursor] [--scope user|project]
42
42
  [--project <id>] [--dry-run] [--yes] [--no-login] [--json]
43
+ [--key-stdin | --no-wait]
43
44
  [--name <label>] [--no-browser] [--timeout <minutes>]
44
45
 
45
46
  Sets CueApril up for this computer and its coding agents:
@@ -54,11 +55,13 @@ Sets CueApril up for this computer and its coding agents:
54
55
  --dry-run Show what would change, with the key masked; change nothing
55
56
  --yes Do not ask for confirmation in a terminal
56
57
  --no-login Fail instead of starting a browser approval when no key is found
58
+ --key-stdin Verify and store an existing agent key from a pipe; never argv or chat
59
+ --no-wait Return the approval link immediately (exit 4); rerun without this flag
57
60
  --json Print one JSON object on stdout
58
61
  --name, --no-browser, --timeout Passed to the login step (see cueapril login --help)
59
62
 
60
63
  Rerunning init is safe. Exit codes: 0 set up (even if a project still needs
61
- setup steps), 4 approval timed out, 5 error.`;
64
+ setup steps), 4 approval pending or timed out, 5 error.`;
62
65
 
63
66
  export function bundledSkillPath() {
64
67
  return fileURLToPath(new URL(`./skill/${SKILL_NAME}/SKILL.md`, import.meta.url));
@@ -227,6 +230,8 @@ function parseInitArgs(argv) {
227
230
  'dry-run': { type: 'boolean' },
228
231
  yes: { type: 'boolean', short: 'y' },
229
232
  'no-login': { type: 'boolean' },
233
+ 'key-stdin': { type: 'boolean' },
234
+ 'no-wait': { type: 'boolean' },
230
235
  json: { type: 'boolean' },
231
236
  name: { type: 'string' },
232
237
  'no-browser': { type: 'boolean' },
@@ -278,10 +283,19 @@ function loginArgs(flags) {
278
283
  const args = [];
279
284
  if (flags.name !== undefined) args.push('--name', flags.name);
280
285
  if (flags['no-browser']) args.push('--no-browser');
286
+ if (flags['no-wait']) args.push('--no-wait');
281
287
  if (flags.timeout !== undefined) args.push('--timeout', flags.timeout);
282
288
  return args;
283
289
  }
284
290
 
291
+ // npx and uvx do not create a permanent cueapril executable. Give agents a
292
+ // runnable default plus the matching Python installer and installed forms.
293
+ function installCommands(argv) {
294
+ const quote = (arg) => /^[A-Za-z0-9_.,:/=-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`;
295
+ const suffix = argv.map(quote).join(' ');
296
+ return { npm: `${RUN_COMMAND} ${suffix}`, pypi: `uvx cueapril ${suffix}`, installed: `cueapril ${suffix}` };
297
+ }
298
+
285
299
  function agentPlanLine(item) {
286
300
  const where = item.displayPath ?? item.path;
287
301
  switch (item.action) {
@@ -346,7 +360,7 @@ export async function runInit(argv = [], deps = {}) {
346
360
  try {
347
361
  flags = parseInitArgs(argv);
348
362
  } catch (error) {
349
- writeLine(io.stderr, `${safeText(error.message)}\n\n${INIT_USAGE}`);
363
+ writeLine(io.stderr, `${safeText(redact(error.message))}\n\n${INIT_USAGE}`);
350
364
  return { exitCode: EXIT.error, summary: null };
351
365
  }
352
366
  if (flags.help) {
@@ -373,6 +387,7 @@ export async function runInit(argv = [], deps = {}) {
373
387
  restart: [],
374
388
  next_prompt: NEXT_PROMPT,
375
389
  messages: [],
390
+ next_actions: [],
376
391
  };
377
392
  const finish = (exitCode) => {
378
393
  summary.exit_code = exitCode;
@@ -386,6 +401,10 @@ export async function runInit(argv = [], deps = {}) {
386
401
  summary.base_url = baseUrl;
387
402
  const scope = parseScope(flags.scope);
388
403
  const wanted = parseAgentList(flags.agents);
404
+ if (flags['key-stdin'] && ['no-wait', 'no-browser', 'name', 'timeout'].some((name) => flags[name] !== undefined)) {
405
+ throw new CliError('--key-stdin cannot be combined with browser approval options.');
406
+ }
407
+ if (flags['no-wait'] && flags['no-login']) throw new CliError('--no-wait cannot be combined with --no-login.');
389
408
  let projectId;
390
409
  if (flags.project !== undefined) {
391
410
  projectId = String(flags.project).trim();
@@ -393,7 +412,13 @@ export async function runInit(argv = [], deps = {}) {
393
412
  }
394
413
 
395
414
  // 1. Key.
396
- let resolved = await resolveApiKey(io, { baseUrl });
415
+ let resolved;
416
+ if (flags['key-stdin']) {
417
+ const imported = await importApiKey(io, { dryRun });
418
+ resolved = { key: imported.key, source: 'stdin', path: imported.credentialsPath, saved: imported.saved };
419
+ summary.login = { status: dryRun ? 'verified' : 'imported' };
420
+ if (imported.changed) summary.files_changed.push(displayPath(io, imported.credentialsPath));
421
+ } else resolved = await resolveApiKey(io, { baseUrl });
397
422
  let loggedIn = false;
398
423
  const login = async (reason) => {
399
424
  if (reason) log(reason);
@@ -404,9 +429,22 @@ export async function runInit(argv = [], deps = {}) {
404
429
  ...(result.verificationUrl ? { verification_url: result.verificationUrl, code: result.code } : {}),
405
430
  };
406
431
  if (result.status !== 'approved' || !result.key) {
407
- const code = result.exitCode === EXIT.timeout ? EXIT.timeout : EXIT.error;
432
+ const code = result.status === 'pending' || result.exitCode === EXIT.timeout ? EXIT.timeout : EXIT.error;
433
+ if (result.verificationUrl) {
434
+ const resumeArgv = ['init', ...argv.filter((arg) => arg !== '--no-wait')];
435
+ const commands = installCommands(resumeArgv);
436
+ const resumeCommand = commands.npm;
437
+ summary.login.resume_command = resumeCommand;
438
+ summary.login.resume_commands = commands;
439
+ summary.next_actions = [
440
+ { action: 'approve_in_browser', owner: 'administrator', verification_url: result.verificationUrl, code: result.code },
441
+ { action: 'resume_init', command: resumeCommand, commands, argv: resumeArgv },
442
+ ];
443
+ }
408
444
  summary.messages.push(
409
- code === EXIT.timeout
445
+ result.status === 'pending'
446
+ ? 'Approval is required. Open the verification link, check the code, then run resume_command; it reuses this request.'
447
+ : code === EXIT.timeout
410
448
  ? 'Approval was not received in time. Run `cueapril init` again to keep waiting; the link and code stay the same.'
411
449
  : 'Login did not complete.',
412
450
  );
@@ -423,6 +461,13 @@ export async function runInit(argv = [], deps = {}) {
423
461
  if (!resolved) {
424
462
  if (dryRun) summary.login = { status: 'skipped', reason: 'dry run: no key yet; a real run asks for approval' };
425
463
  else if (flags['no-login']) {
464
+ summary.login = { status: 'auth_required' };
465
+ const importCommands = installCommands(['init', '--key-stdin', '--json']);
466
+ const approvalCommands = installCommands(['init', '--no-wait', '--no-browser', '--json']);
467
+ summary.next_actions = [
468
+ { action: 'provide_api_key', environment_variable: 'CUEAPRIL_API_KEY', secure_input_command: importCommands.npm, commands: importCommands, argv: ['init', '--key-stdin', '--json'], message: 'Supply the key through a secret manager or local secure input, never in chat.' },
469
+ { action: 'browser_approval', command: approvalCommands.npm, commands: approvalCommands, argv: ['init', '--no-wait', '--no-browser', '--json'] },
470
+ ];
426
471
  throw new CliError('No CueApril key found. Set CUEAPRIL_API_KEY, run `cueapril login`, or run init without --no-login.');
427
472
  } else resolved = await login();
428
473
  }
@@ -584,7 +629,7 @@ export async function runInit(argv = [], deps = {}) {
584
629
  } catch (error) {
585
630
  const message = safeText(redact(error.message, key ? [key] : []), 500);
586
631
  if (!error.reported) summary.messages.push(message);
587
- log(`Error: ${message}`);
632
+ log(summary.login.status === 'pending' ? message : `Error: ${message}`);
588
633
  return finish(error.exitCode ?? EXIT.error);
589
634
  }
590
635
  }
package/key-store.mjs CHANGED
@@ -12,6 +12,7 @@ import {
12
12
  defaultDeps,
13
13
  homeDir,
14
14
  isPosix,
15
+ isTTY,
15
16
  pathFor,
16
17
  safeText,
17
18
  } from './io.mjs';
@@ -23,6 +24,45 @@ export const CREDENTIALS_FILE = 'credentials.json';
23
24
  const FILE_VERSION = 1;
24
25
  const MAX_FILE_BYTES = 1_000_000;
25
26
 
27
+ /** Read an explicitly supplied key without ever echoing it or taking it in argv. */
28
+ export async function readApiKeyStdin(deps = {}) {
29
+ const io = defaultDeps(deps);
30
+ if (isTTY(io.stdin)) {
31
+ throw new CredentialsError('--key-stdin needs a pipe, not a terminal. Supply the key through a secret manager or set CUEAPRIL_API_KEY; never paste it into chat.');
32
+ }
33
+ if (typeof io.stdin?.on !== 'function' || io.stdin.readableEnded || io.stdin.destroyed) {
34
+ throw new CredentialsError('--key-stdin needs a readable pipe containing one CueApril agent key.');
35
+ }
36
+ return new Promise((resolve, reject) => {
37
+ let input = '';
38
+ let settled = false;
39
+ const finish = (error) => {
40
+ if (settled) return;
41
+ settled = true;
42
+ clearTimeout(timer);
43
+ io.stdin.removeListener('data', onData);
44
+ io.stdin.removeListener('end', onEnd);
45
+ io.stdin.removeListener('error', onError);
46
+ io.stdin.pause?.();
47
+ if (error) return reject(error);
48
+ const key = input.trim();
49
+ if (!AGENT_KEY_PATTERN.test(key)) return reject(new CredentialsError('Standard input must contain exactly one complete CueApril agent key. Nothing was saved.'));
50
+ resolve(key);
51
+ };
52
+ const onData = (chunk) => {
53
+ input += String(chunk);
54
+ if (Buffer.byteLength(input, 'utf8') > 1024) finish(new CredentialsError('The --key-stdin input exceeds 1024 bytes. Nothing was saved.'));
55
+ };
56
+ const onEnd = () => finish();
57
+ const onError = () => finish(new CredentialsError('Could not read the key from standard input. Nothing was saved.'));
58
+ const timer = setTimeout(() => finish(new CredentialsError('No complete key arrived on standard input within 10 seconds. Nothing was saved.')), 10_000);
59
+ io.stdin.on('data', onData);
60
+ io.stdin.once('end', onEnd);
61
+ io.stdin.once('error', onError);
62
+ io.stdin.resume?.();
63
+ });
64
+ }
65
+
26
66
  export class CredentialsError extends CliError {
27
67
  constructor(message) {
28
68
  super(message, { code: 'credentials' });
package/login.mjs CHANGED
@@ -22,6 +22,7 @@ import {
22
22
  displayPath,
23
23
  isTTY,
24
24
  pathFor,
25
+ redact,
25
26
  safeText,
26
27
  writeLine,
27
28
  } from './io.mjs';
@@ -34,6 +35,7 @@ import {
34
35
  deleteCredential,
35
36
  maskKey,
36
37
  readCredential,
38
+ readApiKeyStdin,
37
39
  sanitiseCredentialRecord,
38
40
  writeCredential,
39
41
  } from './key-store.mjs';
@@ -52,6 +54,7 @@ const DEVICE_SECRET = /^[A-Za-z0-9_-]{43}$/;
52
54
  const REQUEST_ID = /^[0-9a-f]{64}$/;
53
55
 
54
56
  export const LOGIN_USAGE = `Usage: cueapril login [--name <label>] [--no-browser] [--print-key] [--timeout <minutes>] [--no-wait] [--new] [--json]
57
+ cueapril login --key-stdin [--json]
55
58
 
56
59
  Connects this computer to CueApril. Open the link it prints, check the code,
57
60
  and approve (an organisation owner or admin must approve). The key is saved in
@@ -64,6 +67,7 @@ your user configuration and is never printed unless you pass --print-key.
64
67
  --no-wait Print the link and exit; run login or init again to finish
65
68
  --new Discard a pending request and start a new one
66
69
  --json Print machine-readable JSON lines on stdout
70
+ --key-stdin Verify and store an existing agent key from a pipe; never argv or chat
67
71
 
68
72
  Exit codes: 0 approved, 4 timed out, 5 error.`;
69
73
 
@@ -237,6 +241,7 @@ function parseLoginArgs(argv) {
237
241
  'print-key': { type: 'boolean' },
238
242
  timeout: { type: 'string' },
239
243
  'no-wait': { type: 'boolean' },
244
+ 'key-stdin': { type: 'boolean' },
240
245
  new: { type: 'boolean' },
241
246
  json: { type: 'boolean' },
242
247
  help: { type: 'boolean', short: 'h' },
@@ -249,6 +254,31 @@ function listText(list) {
249
254
  return Array.isArray(list) && list.length ? list.join(', ') : 'none listed';
250
255
  }
251
256
 
257
+ /** Explicit key import is independent of the resumable browser approval flow. */
258
+ export async function importApiKey(deps = {}, { dryRun = false } = {}) {
259
+ const io = defaultDeps(deps);
260
+ if (['CUEAPRIL_API_KEY', 'TENHAW_TOKEN'].some((name) => typeof io.env[name] === 'string' && io.env[name].trim())) {
261
+ throw new CliError('--key-stdin cannot be combined with CUEAPRIL_API_KEY or TENHAW_TOKEN. Use the environment key, or unset it before importing.');
262
+ }
263
+ const baseUrl = resolveBaseUrl(io.env);
264
+ const key = await readApiKeyStdin(io);
265
+ try {
266
+ // Unlike check_setup, this read works when the key covers multiple projects.
267
+ await createHttpClient(io, { baseUrl }).callTool('cueapril_list_projects', {}, key, { timeoutMs: 30_000 });
268
+ } catch (error) {
269
+ throw new CliError(`${safeText(redact(error.message, [key]), 400)} Nothing was saved.`, { code: error.code ?? 'error' });
270
+ }
271
+ const previous = await readCredential(baseUrl, io).catch(() => null);
272
+ const changed = !dryRun && previous?.key !== key;
273
+ let credentialsPath = previous?.key === key ? pathFor(io).join(configDir(io), 'credentials.json') : null;
274
+ try {
275
+ if (changed) ({ path: credentialsPath } = await writeCredential(baseUrl, { key }, io));
276
+ } catch (error) {
277
+ throw new CliError(`Key verified, but local storage could not be confirmed: ${safeText(redact(error.message, [key]), 300)}`, { code: error.code ?? 'error' });
278
+ }
279
+ return { exitCode: EXIT.ok, status: 'imported', key, credentialsPath, saved: !dryRun, changed, baseUrl };
280
+ }
281
+
252
282
  /**
253
283
  * Runs the device approval flow. Returns
254
284
  * { exitCode, status, key?, record?, credentialsPath?, verificationUrl?, code? };
@@ -261,7 +291,7 @@ export async function runLogin(argv = [], deps = {}, options = {}) {
261
291
  try {
262
292
  flags = parseLoginArgs(argv);
263
293
  } catch (error) {
264
- writeLine(io.stderr, `${safeText(error.message)}\n\n${LOGIN_USAGE}`);
294
+ writeLine(io.stderr, `${safeText(redact(error.message))}\n\n${LOGIN_USAGE}`);
265
295
  return { exitCode: EXIT.error, status: 'error' };
266
296
  }
267
297
  if (flags.help) {
@@ -275,6 +305,15 @@ export async function runLogin(argv = [], deps = {}, options = {}) {
275
305
  };
276
306
  let pending;
277
307
  try {
308
+ if (flags['key-stdin']) {
309
+ if (['name', 'no-browser', 'print-key', 'timeout', 'no-wait', 'new'].some((name) => flags[name] !== undefined)) {
310
+ throw new CliError('--key-stdin cannot be combined with browser approval or --print-key options.');
311
+ }
312
+ const imported = await importApiKey(io);
313
+ writeLine(io.stderr, `Verified and saved key ${maskKey(imported.key)} to ${displayPath(io, imported.credentialsPath)}.`);
314
+ emitJson(io, mode, { event: 'login_imported', base_url: imported.baseUrl, credentials_path: displayPath(io, imported.credentialsPath), saved: true, exit_code: EXIT.ok });
315
+ return imported;
316
+ }
278
317
  const baseUrl = resolveBaseUrl(io.env);
279
318
  const timeoutMinutes = parseTimeoutMinutes(flags.timeout);
280
319
  const requestedName = flags.name === undefined ? undefined : parseLabel(flags.name);
@@ -318,7 +357,7 @@ export async function runLogin(argv = [], deps = {}, options = {}) {
318
357
  writeLine(io.stderr, `Waiting up to ${formatMinutes(timeoutMinutes)} for approval...`);
319
358
  return await pollForApproval({ io, mode, baseUrl, pending, announce, timeoutMs: timeoutMinutes * 60_000 });
320
359
  } catch (error) {
321
- const message = safeText(error.message, 500);
360
+ const message = safeText(redact(error.message), 500);
322
361
  writeLine(io.stderr, `Error: ${message}`);
323
362
  emitJson(io, mode, { event: 'login_failed', reason: error.code ?? 'error', message });
324
363
  return { exitCode: error.exitCode ?? EXIT.error, status: 'error' };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cueapril",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "CueApril CLI: connect your coding agent to CueApril in one command, then test pull requests and read verdicts, findings and suggested fixes from the terminal.",
5
5
  "keywords": [
6
6
  "cueapril",
@@ -12,21 +12,22 @@ CueApril tests a pull request in a disposable VM under a test plan the team appr
12
12
  Once per session, before relying on CueApril, run:
13
13
 
14
14
  ```bash
15
- npx -y --package=https://app.cueapril.com/downloads/cueapril-cli-1.1.0.tgz cueapril doctor
15
+ npx -y cueapril@latest doctor
16
16
  ```
17
17
 
18
18
  If it reports a problem, run:
19
19
 
20
20
  ```bash
21
- npx -y --package=https://app.cueapril.com/downloads/cueapril-cli-1.1.0.tgz cueapril init
21
+ npx -y cueapril@latest init
22
22
  ```
23
23
 
24
24
  `init` connects this computer to CueApril, adds the `cueapril` MCP server to the coding agents it finds (user level only, never inside the repository) and installs this skill. If it needs a key it prints a link and a code, and may open a browser. Give the person the link and the code exactly as printed and ask them to approve; an organisation owner or admin must do it, once.
25
25
 
26
- - If your shell stops long commands, run `npx -y --package=https://app.cueapril.com/downloads/cueapril-cli-1.1.0.tgz cueapril login --no-wait --json` first, give the person the link and code, then run `init`. It resumes the same request, so the link stays valid. Rerunning `init` after a timeout also resumes it.
26
+ - If the person wants to supply an API key, run `npx -y cueapril@latest init --no-login --json`. Missing credentials return exit 5, `login.status: "auth_required"` and `next_actions`. Ask for secure local input or a secret manager setting `CUEAPRIL_API_KEY`, never a key in chat. A secret manager can pipe the key to `npx -y cueapril@latest init --key-stdin --json`; the CLI verifies and stores it without printing it. Do not run `echo <key>` or put a literal key on a command line.
27
+ - If your shell stops long commands, run `npx -y cueapril@latest init --no-wait --no-browser --json` first. Exit 4, `login.status: "pending"` and `next_actions` identify the approval step. Give the person `login.verification_url` and `login.code`, then execute `login.resume_command` after approval (`login.resume_commands.pypi` when using uvx). Reuse your installer; npx and uvx do not install a persistent `cueapril` executable. It resumes the same request, so the link stays valid. Rerunning `init` after a timeout also resumes it.
27
28
  - If `init` or `doctor` lists setup steps with links (for example installing the GitHub App), pass them to the person. Only they can do these in the browser.
28
29
  - New MCP servers load when the agent restarts. If the `cueapril_*` tools are missing in this session, use the CLI (section 3).
29
- - Once CueApril publishes the `cueapril` package on npm, `npx -y cueapril@latest`, `pnpm dlx cueapril`, `bunx cueapril` or `yarn dlx cueapril` can replace the longer command used here; https://app.cueapril.com/agents/README.md shows the current form.
30
+ - The public npm package is `cueapril`; `pnpm dlx cueapril`, `bunx cueapril` and `yarn dlx cueapril` also work. PyPI's `cueapril` package uses the same CLI: `uvx cueapril init` (Python 3.10+ and installed Node.js 20+).
30
31
 
31
32
  ## 2. The loop with MCP tools
32
33
 
@@ -42,10 +43,10 @@ Also available: `cueapril_check_setup`, `cueapril_list_assessments`, `cueapril_l
42
43
  ## 3. The loop with the CLI
43
44
 
44
45
  ```bash
45
- npx -y --package=https://app.cueapril.com/downloads/cueapril-cli-1.1.0.tgz cueapril assess --pr 123 --wait --json
46
+ npx -y cueapril@latest assess --pr 123 --wait --json
46
47
  ```
47
48
 
48
- It starts (or reuses) the assessment for pull request 123, waits, prints machine-readable results and sets the exit code in section 7. It uses the key that `init` stored, or `CUEAPRIL_API_KEY`. Run `npx -y --package=https://app.cueapril.com/downloads/cueapril-cli-1.1.0.tgz cueapril --help` for status, wait, results and cancel. Give it a long timeout, or run it in the background and read its JSON when it exits.
49
+ It starts (or reuses) the assessment for pull request 123, waits, prints machine-readable results and sets the exit code in section 7. It uses the key that `init` stored, or `CUEAPRIL_API_KEY`. Run `npx -y cueapril@latest --help` for status, wait, results and cancel. Give it a long timeout, or run it in the background and read its JSON when it exits.
49
50
 
50
51
  ## 4. Wait without wasting tokens
51
52
 
@@ -84,6 +85,6 @@ It starts (or reuses) the assessment for pull request 123, waits, prints machine
84
85
  ## 8. Keep the key secret
85
86
 
86
87
  - Never print, echo, log or commit the CueApril key, and never put it in a prompt, pull request, issue or chat. `init` keeps it in the person's user configuration and the agents' MCP settings, never in the repository.
87
- - Do not open credential or MCP configuration files to read the key. `npx -y --package=https://app.cueapril.com/downloads/cueapril-cli-1.1.0.tgz cueapril doctor` reports what is configured, with the key masked.
88
- - If a tool says the key is missing, expired or revoked, run `npx -y --package=https://app.cueapril.com/downloads/cueapril-cli-1.1.0.tgz cueapril init` (it asks for a new approval); do not search for a key. If a call is refused as not allowed (HTTP 403), the key lacks that permission or does not cover the project, and `init` would keep the same key: tell the person that an organisation owner or admin must approve a key with Run assessments access to this project. If a key may have leaked, run `npx -y --package=https://app.cueapril.com/downloads/cueapril-cli-1.1.0.tgz cueapril logout`, which revokes it, then `init`.
88
+ - Do not open credential or MCP configuration files to read the key. `npx -y cueapril@latest doctor` reports what is configured, with the key masked.
89
+ - If a tool says the key is missing, expired or revoked, run `npx -y cueapril@latest init` (it asks for a new approval); do not search for a key. If a call is refused as not allowed (HTTP 403), the key lacks that permission or does not cover the project, and `init` would keep the same key: tell the person that an organisation owner or admin must approve a key with Run assessments access to this project. If a key may have leaked, run `npx -y cueapril@latest logout`, which revokes it, then `init`.
89
90
  - Each assessment reserves at most 300p (£3.00), and the key may carry a 30-day spend cap.