@singularity-layer/cli 0.2.1 → 0.3.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
@@ -7,8 +7,8 @@ npm i -g @singularity-layer/cli
7
7
  singularity --help
8
8
  ```
9
9
 
10
- Requires Node 20+ and a Solana keypair (`solana-keygen new`). No account, no API key, no dashboard
11
- login — your wallet *is* the account.
10
+ Requires Node 20+ and either a Solana keypair (`solana-keygen new`) or a compute API key. No
11
+ account and no dashboard login — your wallet *is* the account.
12
12
 
13
13
  ## Processors
14
14
 
@@ -152,11 +152,36 @@ singularity processors run '{"n":1}' --json
152
152
 
153
153
  ## Auth
154
154
 
155
- A per-request Solana wallet signature, using `~/.config/solana/id.json` by default (`--keypair
156
- <path>`, `SINGULARITY_KEYPAIR`, or `singularity processors configure` to change it). **The key never
157
- leaves your machine** — only a signature is sent, and it covers the method, the path and a hash of the
155
+ Two ways in. The CLI picks the API key when one is given, and the keypair otherwise.
156
+
157
+ **Wallet signature (default).** Uses `~/.config/solana/id.json` (`--keypair <path>`,
158
+ `SINGULARITY_KEYPAIR`, or `singularity processors configure` to change it). **The key never leaves
159
+ your machine** — only a signature is sent, and it covers the method, the path and a hash of the
158
160
  body, so it authorizes exactly one request and cannot be replayed against another.
159
161
 
162
+ **Compute API key.** `--api-key x402c_...`, or `SGL_API_KEY` in the environment. This is the option
163
+ for CI and for agents, where there is no keypair to hold.
164
+
165
+ ```bash
166
+ export SGL_API_KEY=x402c_...
167
+ singularity whoami # the wallet the key resolves to
168
+ singularity processors list
169
+ singularity processors deploy
170
+ ```
171
+
172
+ Mint the key in the dashboard with the `processors:write` scope, or `processors:read` if you only
173
+ need the read commands. Two things to know before you rely on it:
174
+
175
+ - **`processors:write` is full control** of that wallet's processors, delete and secrets included.
176
+ A bearer credential cannot be bound to one request the way a signature is, so scope is the only
177
+ control. Mint `processors:read` if you want something that cannot change anything.
178
+ - **`deploy` needs a key minted on a Solana wallet.** That address becomes your payout account, so
179
+ a key on an EVM wallet gets `400 solana_wallet_required`. It can still manage processors its
180
+ wallet already owns.
181
+
182
+ An API key never expires, and there is no audit log of what it did. Revoking it in the dashboard is
183
+ the only way to stop it.
184
+
160
185
  ## Programmatic use
161
186
 
162
187
  ```ts
package/dist/auth.d.ts CHANGED
@@ -42,9 +42,39 @@ export declare function bs58(bytes: Uint8Array): string;
42
42
  * the machine — only a signature is sent.
43
43
  */
44
44
  export declare function loadKeypair(flags?: Flags): Keypair;
45
+ /** Either credential the control plane accepts. Exactly one is ever set. */
46
+ export interface Creds {
47
+ kp?: Keypair;
48
+ apiKey?: string;
49
+ }
50
+ /**
51
+ * Resolve how this invocation authenticates.
52
+ *
53
+ * An API KEY WINS when one is given, because asking for it is explicit: `--api-key` on the command
54
+ * line, or SGL_API_KEY in the environment. Falling back to the keypair when a key is present would
55
+ * mean a CI job with SGL_API_KEY set silently signed with whatever keypair happened to be on the
56
+ * runner, which is the opposite of what was asked for.
57
+ *
58
+ * Otherwise it is the keypair, exactly as before, so nothing about the existing workflow changes.
59
+ */
60
+ /**
61
+ * Is there a credential to load at all? For commands that work unauthenticated on public data and
62
+ * should not die just because this machine has no keypair.
63
+ */
64
+ export declare function hasAnyCredential(flags?: Flags): boolean;
65
+ export declare function loadCreds(flags?: Flags): Creds;
45
66
  export interface ApiOpts {
46
67
  body?: unknown;
47
68
  kp?: Keypair;
69
+ /**
70
+ * Compute API key (`x402c_…`), sent as `X-API-Key`.
71
+ *
72
+ * MUTUALLY EXCLUSIVE WITH `kp` in practice: loadCreds returns one or the other, never both.
73
+ * The server accepts either, and presenting both would just mean the key decides, but keeping
74
+ * them exclusive at the source means there is never a question about which one authorised an
75
+ * action when reading a log.
76
+ */
77
+ apiKey?: string;
48
78
  bearer?: string;
49
79
  /**
50
80
  * Query parameters. An ARRAY value becomes REPEATED keys (`?tag=a&tag=b`), which is exactly what
@@ -88,7 +118,7 @@ export interface ApiOpts {
88
118
  *
89
119
  * Found by adversarial review after I had written exactly that. The rule is: match the route.
90
120
  */
91
- export declare function api<T = unknown>(base: string, method: NonNullable<ApiOpts['method']>, path: string, { body, kp, bearer, query, signQuery }?: ApiOpts): Promise<T>;
121
+ export declare function api<T = unknown>(base: string, method: NonNullable<ApiOpts['method']>, path: string, { body, kp, apiKey, bearer, query, signQuery }?: ApiOpts): Promise<T>;
92
122
  /**
93
123
  * Parse argv into subcommand path, positional args, and flags.
94
124
  *
package/dist/cli.d.ts CHANGED
@@ -11,6 +11,6 @@
11
11
  * • `sglcode` — the agentic coding CLI. A product in its own right, like Claude Code.
12
12
  * Demoting it to `singularity code` would misrepresent what it is.
13
13
  *
14
- * Auth is a per-request Solana wallet signature. The key never leaves the machine.
14
+ * Auth is a per-request Solana wallet signature, or a compute API key. The key never leaves the machine.
15
15
  */
16
16
  export {};
package/dist/cli.js CHANGED
@@ -36,9 +36,14 @@ function loadKeypair(flags = {}) {
36
36
  flags.keypair || process.env.SINGULARITY_KEYPAIR || process.env.SGLPROC_KEYPAIR || join(homedir(), ".config/solana/id.json")
37
37
  );
38
38
  if (!existsSync(path)) {
39
- die(`no keypair at ${path}
40
- pass --keypair <path>, set SINGULARITY_KEYPAIR, or create one:
41
- solana-keygen new`);
39
+ die(
40
+ `no credential found
41
+ no keypair at ${path}
42
+ pass --keypair <path>, or set SINGULARITY_KEYPAIR, or create one:
43
+ solana-keygen new
44
+ or authenticate with a compute API key instead:
45
+ --api-key x402c_... (also read from SGL_API_KEY)`
46
+ );
42
47
  }
43
48
  let raw;
44
49
  try {
@@ -54,11 +59,35 @@ function loadKeypair(flags = {}) {
54
59
  const pair = nacl.sign.keyPair.fromSecretKey(secret);
55
60
  return { secretKey: pair.secretKey, address: bs58(pair.publicKey) };
56
61
  }
62
+ function hasAnyCredential(flags = {}) {
63
+ if ("api-key" in flags) return true;
64
+ if ((process.env.SGL_API_KEY || process.env.SINGULARITY_API_KEY || "").trim()) return true;
65
+ const path = String(
66
+ flags.keypair || process.env.SINGULARITY_KEYPAIR || process.env.SGLPROC_KEYPAIR || join(homedir(), ".config/solana/id.json")
67
+ );
68
+ return existsSync(path);
69
+ }
70
+ function loadCreds(flags = {}) {
71
+ if ("api-key" in flags && typeof flags["api-key"] !== "string") {
72
+ die("--api-key needs a value:\n --api-key x402c_...\n or set SGL_API_KEY, which keeps it out of your shell history");
73
+ }
74
+ const equalsForm = Object.keys(flags).find((k) => k.startsWith("api-key="));
75
+ if (equalsForm) {
76
+ die(`--api-key=VALUE is not supported; use a space:
77
+ --api-key ${equalsForm.slice("api-key=".length) || "x402c_..."}`);
78
+ }
79
+ const flagKey = typeof flags["api-key"] === "string" ? String(flags["api-key"]).trim() : "";
80
+ if ("api-key" in flags && !flagKey) die("--api-key was given an empty value");
81
+ if (flagKey) return { apiKey: flagKey };
82
+ const envKey = (process.env.SGL_API_KEY || process.env.SINGULARITY_API_KEY || "").trim();
83
+ if (envKey) return { apiKey: envKey };
84
+ return { kp: loadKeypair(flags) };
85
+ }
57
86
  async function sha256Hex(input) {
58
87
  const d = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
59
88
  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
60
89
  }
61
- async function api(base, method, path, { body, kp, bearer, query, signQuery } = {}) {
90
+ async function api(base, method, path, { body, kp, apiKey, bearer, query, signQuery } = {}) {
62
91
  let qs = "";
63
92
  if (query) {
64
93
  const params = new URLSearchParams();
@@ -74,6 +103,8 @@ async function api(base, method, path, { body, kp, bearer, query, signQuery } =
74
103
  const headers = {};
75
104
  if (sentRaw) headers["content-type"] = "application/json";
76
105
  if (bearer) headers.Authorization = `Bearer ${bearer}`;
106
+ if (kp && apiKey) die("pass either a keypair or an apiKey to api(), never both");
107
+ if (apiKey) headers["X-API-Key"] = apiKey;
77
108
  if (kp) {
78
109
  const timestamp = String(Math.floor(Date.now() / 1e3));
79
110
  const nonce = [...nacl.randomBytes(12)].map((b) => b.toString(16).padStart(2, "0")).join("");
@@ -383,7 +414,33 @@ var HELP = `singularity processors \u2014 deploy loops we host and run
383
414
  --slug <slug> when not run from a processor directory
384
415
  --json machine-readable output, for scripts and agents
385
416
  --bundle bundle with esbuild: imports and npm packages
386
- --entry <file> bundle entry (default: the manifest's $code)`;
417
+ --entry <file> bundle entry (default: the manifest's $code)
418
+
419
+ Getting paid. Buyers pay YOU directly \u2014 we never hold the money and take no cut. By default that
420
+ is USDC on Solana at your signing wallet. To be paid on more than one chain, add a "payout" block
421
+ to processor.json:
422
+
423
+ "payout": {
424
+ "solana": "<base58 wallet>", USDC
425
+ "base": "0x\u2026", USDC
426
+ "robinhood": "0x\u2026" USDG on Robinhood Chain
427
+ }
428
+
429
+ One price_usd covers all three (every asset is 6-decimal), and buyers pick a chain from the 402.
430
+ Name only the chains you want: a chain you leave out is never offered. Check each address twice \u2014
431
+ a payment cannot be reversed.`;
432
+ var PAYOUT_CHAINS = ["solana", "base", "robinhood"];
433
+ function checkPayoutAddress(chain, value) {
434
+ if (typeof value !== "string" || !value.trim()) return "must be a non-empty string";
435
+ const addr = value.trim();
436
+ if (chain === "solana") {
437
+ if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(addr)) return "must be a base58 Solana address";
438
+ return null;
439
+ }
440
+ if (!/^0x[0-9a-fA-F]{40}$/.test(addr)) return "must be a 0x-prefixed 20-byte hex address";
441
+ if (/^0x0{40}$/.test(addr)) return "the zero address cannot receive payment";
442
+ return null;
443
+ }
387
444
  var STARTER_MANIFEST = (slug) => ({
388
445
  $code: "processor.js",
389
446
  manifest_version: 1,
@@ -440,11 +497,31 @@ var readConfig = () => {
440
497
  function loadManifest(flags) {
441
498
  const p = resolve(String(flags.manifest || "processor.json"));
442
499
  if (!existsSync3(p)) die(`no manifest at ${p} \u2014 run \`singularity processors init\` first`);
500
+ let m;
443
501
  try {
444
- return JSON.parse(readFileSync3(p, "utf8"));
502
+ m = JSON.parse(readFileSync3(p, "utf8"));
445
503
  } catch {
446
504
  return die(`${p} is not valid JSON`);
447
505
  }
506
+ checkPayout(m);
507
+ return m;
508
+ }
509
+ function checkPayout(m) {
510
+ if (m.payout === void 0) return;
511
+ if (typeof m.payout !== "object" || m.payout === null || Array.isArray(m.payout)) {
512
+ die('payout must be an object keyed by chain, e.g. { "solana": "\u2026", "base": "0x\u2026" }');
513
+ }
514
+ const entries = Object.entries(m.payout);
515
+ if (entries.length === 0) {
516
+ die("payout names no chain \u2014 remove it entirely to be paid in USDC on Solana at your signing wallet");
517
+ }
518
+ for (const [chain, value] of entries) {
519
+ if (!PAYOUT_CHAINS.includes(chain)) {
520
+ die(`payout.${chain}: unknown chain \u2014 supported: ${PAYOUT_CHAINS.join(", ")}`);
521
+ }
522
+ const problem = checkPayoutAddress(chain, value);
523
+ if (problem) die(`payout.${chain}: ${problem}`);
524
+ }
448
525
  }
449
526
  var clean = (m) => Object.fromEntries(Object.entries(m).filter(([k]) => !k.startsWith("$")));
450
527
  function resolveSlug(flags) {
@@ -550,15 +627,15 @@ function toQuery(input) {
550
627
  }
551
628
  return out;
552
629
  }
553
- async function invokeAndWait(base, slug, input, kp, token, quiet, asGet = false) {
630
+ async function invokeAndWait(base, slug, input, creds, token, quiet, asGet = false) {
554
631
  let res = asGet ? await api(base, "GET", `/processors/${slug}/run`, {
555
632
  query: toQuery(input),
556
- kp,
633
+ ...creds.kp ? { kp: creds.kp } : {},
557
634
  bearer: token,
558
635
  signQuery: true
559
636
  }) : await api(base, "POST", `/processors/${slug}/run`, {
560
637
  body: { input },
561
- kp,
638
+ ...creds.kp ? { kp: creds.kp } : {},
562
639
  bearer: token
563
640
  });
564
641
  if (res.status !== "completed" && res.run_token && res.run_id) {
@@ -627,12 +704,12 @@ async function run(words, flags) {
627
704
  break;
628
705
  }
629
706
  case "deploy": {
630
- const kp = loadKeypair(flags);
707
+ const creds = loadCreds(flags);
631
708
  const manifest = loadManifest(flags);
632
709
  const source = await resolveSource(manifest, flags);
633
710
  const res = await api(BASE, "POST", "/processors", {
634
711
  body: { manifest: clean(manifest), ...source },
635
- kp
712
+ ...creds
636
713
  });
637
714
  writeState({ slug: res.slug, invoke_token: res.invoke_token });
638
715
  if (emit(flags, res)) break;
@@ -647,7 +724,7 @@ async function run(words, flags) {
647
724
  break;
648
725
  }
649
726
  case "update": {
650
- const kp = loadKeypair(flags);
727
+ const creds = loadCreds(flags);
651
728
  const manifest = loadManifest(flags);
652
729
  const slug = String(flags.slug || manifest.slug || die("no slug in processor.json"));
653
730
  const source = await resolveSource(manifest, flags);
@@ -655,7 +732,7 @@ async function run(words, flags) {
655
732
  BASE,
656
733
  "PATCH",
657
734
  `/processors/${slug}`,
658
- { body: { manifest: clean(manifest), ...source }, kp }
735
+ { body: { manifest: clean(manifest), ...source }, ...creds }
659
736
  );
660
737
  if (emit(flags, res)) break;
661
738
  ok(`updated ${slug} (config_rev ${res.config_rev})`);
@@ -668,7 +745,7 @@ async function run(words, flags) {
668
745
  const slug = requireSlug(flags);
669
746
  const token = String(flags.token || readState().invoke_token || "");
670
747
  if (!token) die(`no invoke token in ${STATE_FILE} \u2014 run \`singularity processors rotate\``);
671
- const kp = loadKeypair(flags);
748
+ const creds = loadCreds(flags);
672
749
  let input = {};
673
750
  const interactive = flags.interactive === true || sub === "call";
674
751
  if (words[1]) {
@@ -682,7 +759,7 @@ async function run(words, flags) {
682
759
  BASE,
683
760
  "GET",
684
761
  `/processors/${slug}`,
685
- { kp }
762
+ { ...creds }
686
763
  );
687
764
  input = await promptForSchema(d.manifest?.input_schema ?? d.input_schema);
688
765
  ok(`input: ${JSON.stringify(input)}`);
@@ -691,7 +768,7 @@ async function run(words, flags) {
691
768
  BASE,
692
769
  slug,
693
770
  input,
694
- kp,
771
+ creds,
695
772
  token,
696
773
  flags.json === true,
697
774
  flags.get === true
@@ -701,13 +778,9 @@ async function run(words, flags) {
701
778
  }
702
779
  case "schema": {
703
780
  const slug = words[1] || requireSlug(flags);
704
- let kp;
705
- try {
706
- kp = loadKeypair(flags);
707
- } catch {
708
- kp = void 0;
709
- }
710
- const d = await api(BASE, "GET", `/processors/${slug}`, kp ? { kp } : {});
781
+ let creds;
782
+ creds = hasAnyCredential(flags) ? loadCreds(flags) : void 0;
783
+ const d = await api(BASE, "GET", `/processors/${slug}`, creds ? { ...creds } : {});
711
784
  const input = d.manifest?.input_schema ?? d.input_schema;
712
785
  const output = d.manifest?.output_schema ?? d.output_schema;
713
786
  if (emit(flags, { slug, input_schema: input, output_schema: output })) break;
@@ -724,7 +797,7 @@ async function run(words, flags) {
724
797
  break;
725
798
  }
726
799
  case "secrets": {
727
- const kp = loadKeypair(flags);
800
+ const creds = loadCreds(flags);
728
801
  const slug = requireSlug(flags);
729
802
  const pairs = words.slice(1);
730
803
  if (!pairs.length) die("usage: singularity processors secrets KEY=value [KEY2=value2] (KEY= clears)");
@@ -739,7 +812,7 @@ async function run(words, flags) {
739
812
  BASE,
740
813
  "PUT",
741
814
  `/processors/${slug}/secrets`,
742
- { body: { values }, kp }
815
+ { body: { values }, ...creds }
743
816
  );
744
817
  if (emit(flags, res)) break;
745
818
  ok(`secrets set: ${res.secrets.join(", ") || "(none)"}`);
@@ -749,11 +822,11 @@ async function run(words, flags) {
749
822
  break;
750
823
  }
751
824
  case "env": {
752
- const kp = loadKeypair(flags);
825
+ const creds = loadCreds(flags);
753
826
  const slug = requireSlug(flags);
754
827
  const action = words[1] || "list";
755
828
  if (action === "list") {
756
- const d = await api(BASE, "GET", `/processors/${slug}`, { kp });
829
+ const d = await api(BASE, "GET", `/processors/${slug}`, { ...creds });
757
830
  const declared = d.manifest?.secrets ?? [];
758
831
  const set = new Set(d.secret_keys ?? []);
759
832
  const modes = d.secret_modes ?? {};
@@ -782,7 +855,7 @@ async function run(words, flags) {
782
855
  BASE,
783
856
  "PUT",
784
857
  `/processors/${slug}/secrets`,
785
- { body: { values: { [key]: null } }, kp }
858
+ { body: { values: { [key]: null } }, ...creds }
786
859
  );
787
860
  if (emit(flags, res)) break;
788
861
  ok(`cleared ${key}`);
@@ -793,8 +866,8 @@ async function run(words, flags) {
793
866
  break;
794
867
  }
795
868
  case "list": {
796
- const kp = loadKeypair(flags);
797
- const res = await api(BASE, "GET", "/processors", { kp });
869
+ const creds = loadCreds(flags);
870
+ const res = await api(BASE, "GET", "/processors", { ...creds });
798
871
  if (emit(flags, res)) break;
799
872
  if (!res.processors.length) {
800
873
  ok("no processors yet \u2014 singularity processors init");
@@ -834,18 +907,18 @@ async function run(words, flags) {
834
907
  break;
835
908
  }
836
909
  case "logs": {
837
- const kp = loadKeypair(flags);
910
+ const creds = loadCreds(flags);
838
911
  const slug = words[1] || requireSlug(flags);
839
912
  const limit = Number(flags.limit || 30);
840
913
  if (flags.follow === true) {
841
- await followLogs(BASE, slug, kp, limit);
914
+ await followLogs(BASE, slug, creds, limit);
842
915
  break;
843
916
  }
844
917
  const res = await api(
845
918
  BASE,
846
919
  "GET",
847
920
  `/processors/${slug}/runs`,
848
- { kp, query: { limit, ...typeof flags.logs === "string" ? { logs: flags.logs } : {} } }
921
+ { ...creds, query: { limit, ...typeof flags.logs === "string" ? { logs: flags.logs } : {} } }
849
922
  );
850
923
  if (emit(flags, res)) break;
851
924
  printRunsPage(res);
@@ -858,8 +931,8 @@ async function run(words, flags) {
858
931
  break;
859
932
  }
860
933
  case "revenue": {
861
- const kp = loadKeypair(flags);
862
- const res = await api(BASE, "GET", "/processors", { kp });
934
+ const creds = loadCreds(flags);
935
+ const res = await api(BASE, "GET", "/processors", { ...creds });
863
936
  let sales = 0n, salesCount = 0n, spent = 0n, held = 0n;
864
937
  for (const p of res.processors) {
865
938
  sales += BigInt(p.sales_micro ?? 0);
@@ -888,11 +961,19 @@ async function run(words, flags) {
888
961
  break;
889
962
  }
890
963
  case "earnings": {
891
- const kp = loadKeypair(flags);
964
+ const creds = loadCreds(flags);
892
965
  const slug = words[1] || requireSlug(flags);
893
- const res = await api(BASE, "GET", `/processors/${slug}/earnings`, { kp });
966
+ const res = await api(BASE, "GET", `/processors/${slug}/earnings`, { ...creds });
894
967
  if (emit(flags, res)) break;
895
- ok(`Sales $${usd(res.sales.total_micro)} (${res.sales.count} paid runs, sent to ${res.sales.paid_to})`);
968
+ const byChain = res.sales.paid_to_by_chain;
969
+ if (byChain && Object.keys(byChain).length > 1) {
970
+ ok(`Sales $${usd(res.sales.total_micro)} (${res.sales.count} paid runs)`);
971
+ for (const [chain, addr] of Object.entries(byChain)) {
972
+ ok(` ${chain.padEnd(10)} ${addr}`);
973
+ }
974
+ } else {
975
+ ok(`Sales $${usd(res.sales.total_micro)} (${res.sales.count} paid runs, sent to ${res.sales.paid_to})`);
976
+ }
896
977
  ok(`Compute $${usd(res.runtime.spent_micro)} spent from your credit balance`);
897
978
  if (res.runtime.held_open_micro > 0) {
898
979
  ok(`Held $${usd(res.runtime.held_open_micro)} reserved for runs still in flight`);
@@ -907,14 +988,14 @@ async function run(words, flags) {
907
988
  }
908
989
  case "pause":
909
990
  case "resume": {
910
- const kp = loadKeypair(flags);
991
+ const creds = loadCreds(flags);
911
992
  const slug = requireSlug(flags);
912
993
  const paused = sub === "pause";
913
994
  const res = await api(
914
995
  BASE,
915
996
  "PUT",
916
997
  `/processors/${slug}/pause`,
917
- { body: { paused }, kp }
998
+ { body: { paused }, ...creds }
918
999
  );
919
1000
  if (emit(flags, res)) break;
920
1001
  ok(`${slug}: ${res.paused ? "paused" : "running"}`);
@@ -923,27 +1004,27 @@ async function run(words, flags) {
923
1004
  }
924
1005
  case "publish":
925
1006
  case "unpublish": {
926
- const kp = loadKeypair(flags);
1007
+ const creds = loadCreds(flags);
927
1008
  const slug = requireSlug(flags);
928
1009
  const listed = sub === "publish";
929
1010
  const res = await api(
930
1011
  BASE,
931
1012
  "PUT",
932
1013
  `/processors/${slug}/listing`,
933
- { body: { listed }, kp }
1014
+ { body: { listed }, ...creds }
934
1015
  );
935
1016
  if (emit(flags, res)) break;
936
1017
  ok(res.note || (listed ? "published" : "unpublished"));
937
1018
  break;
938
1019
  }
939
1020
  case "rotate": {
940
- const kp = loadKeypair(flags);
1021
+ const creds = loadCreds(flags);
941
1022
  const slug = requireSlug(flags);
942
1023
  const res = await api(
943
1024
  BASE,
944
1025
  "POST",
945
1026
  `/processors/${slug}/rotate-token`,
946
- { kp }
1027
+ { ...creds }
947
1028
  );
948
1029
  writeState({ slug, invoke_token: res.invoke_token });
949
1030
  if (emit(flags, res)) break;
@@ -953,14 +1034,14 @@ async function run(words, flags) {
953
1034
  break;
954
1035
  }
955
1036
  case "delete": {
956
- const kp = loadKeypair(flags);
1037
+ const creds = loadCreds(flags);
957
1038
  const slug = requireSlug(flags);
958
1039
  if (!flags.yes) {
959
1040
  die(`this cannot be undone and the slug "${slug}" can NEVER be reused.
960
1041
  to stop traffic without losing the slug: singularity processors pause
961
1042
  to really delete it, re-run with --yes`);
962
1043
  }
963
- await api(BASE, "DELETE", `/processors/${slug}`, { kp });
1044
+ await api(BASE, "DELETE", `/processors/${slug}`, { ...creds });
964
1045
  ok(`deleted ${slug} (the slug stays reserved)`);
965
1046
  break;
966
1047
  }
@@ -977,12 +1058,12 @@ function printRunsPage(res) {
977
1058
  ok(`${when(r.created_at)} ${r.status.padEnd(16)} ${String(r.run_ms ?? "").padStart(6)}ms ${r.error ? r.error.slice(0, 60) : ""}`);
978
1059
  }
979
1060
  }
980
- async function followLogs(base, slug, kp, limit) {
1061
+ async function followLogs(base, slug, creds, limit) {
981
1062
  const seen = /* @__PURE__ */ new Set();
982
1063
  let first = true;
983
1064
  ok(`following ${slug} \u2014 ctrl-c to stop`);
984
1065
  for (; ; ) {
985
- const res = await api(base, "GET", `/processors/${slug}/runs`, { kp, query: { limit } });
1066
+ const res = await api(base, "GET", `/processors/${slug}/runs`, { ...creds, query: { limit } });
986
1067
  for (const r of [...res.runs].reverse()) {
987
1068
  const key = r.id ?? `${r.created_at}:${r.status}:${r.run_ms}`;
988
1069
  if (seen.has(key)) continue;
@@ -1001,7 +1082,7 @@ async function followLogs(base, slug, kp, limit) {
1001
1082
  }
1002
1083
 
1003
1084
  // src/version.ts
1004
- var VERSION = "0.2.1";
1085
+ var VERSION = "0.3.0";
1005
1086
 
1006
1087
  // src/cli.ts
1007
1088
  var COMMANDS = {
@@ -1013,10 +1094,16 @@ usage: singularity <command> [subcommand] [options]
1013
1094
 
1014
1095
  commands:
1015
1096
  ${Object.entries(COMMANDS).map(([k, v]) => ` ${k.padEnd(14)} ${v.blurb}`).join("\n")}
1016
- whoami print the wallet address your keypair resolves to
1097
+ whoami print the wallet address this credential resolves to
1017
1098
 
1018
1099
  singularity <command> show that command's subcommands
1019
1100
  --keypair <path> defaults to ~/.config/solana/id.json
1101
+ SGL_API_KEY=x402c_... authenticate with a compute API key instead of a keypair.
1102
+ Prefer the env var: --api-key <key> works too, but argv is
1103
+ visible in ps and your shell history. Needs processors:write
1104
+ (processors:read for read-only commands). Cannot deploy unless
1105
+ the key's wallet is a Solana one, since that address becomes
1106
+ your payout account, and 'run' uses the invoke-token lane.
1020
1107
  --json machine-readable output, for scripts and agents
1021
1108
 
1022
1109
  Other Singularity CLIs, deliberately separate:
@@ -1034,8 +1121,17 @@ async function main() {
1034
1121
  process.exit(cmd && cmd !== "help" ? 1 : 0);
1035
1122
  }
1036
1123
  if (cmd === "whoami") {
1037
- const kp = loadKeypair(flags);
1038
- ok(flags.json ? JSON.stringify({ address: kp.address, chain: "solana" }) : kp.address);
1124
+ const creds = loadCreds(flags);
1125
+ if (creds.apiKey) {
1126
+ const res = await api(resolveBase(flags), "GET", "/processors", { ...creds });
1127
+ const owner = res.owner || "";
1128
+ if (!owner) die("the API key is valid but returned no owner wallet");
1129
+ const chain = owner.startsWith("0x") ? "evm" : "solana";
1130
+ ok(flags.json ? JSON.stringify({ address: owner, chain, via: "api-key" }) : owner);
1131
+ return;
1132
+ }
1133
+ const kp = creds.kp;
1134
+ ok(flags.json ? JSON.stringify({ address: kp.address, chain: "solana", via: "keypair" }) : kp.address);
1039
1135
  return;
1040
1136
  }
1041
1137
  const entry = COMMANDS[cmd];
package/dist/index.js CHANGED
@@ -33,9 +33,14 @@ function loadKeypair(flags = {}) {
33
33
  flags.keypair || process.env.SINGULARITY_KEYPAIR || process.env.SGLPROC_KEYPAIR || join(homedir(), ".config/solana/id.json")
34
34
  );
35
35
  if (!existsSync(path)) {
36
- die(`no keypair at ${path}
37
- pass --keypair <path>, set SINGULARITY_KEYPAIR, or create one:
38
- solana-keygen new`);
36
+ die(
37
+ `no credential found
38
+ no keypair at ${path}
39
+ pass --keypair <path>, or set SINGULARITY_KEYPAIR, or create one:
40
+ solana-keygen new
41
+ or authenticate with a compute API key instead:
42
+ --api-key x402c_... (also read from SGL_API_KEY)`
43
+ );
39
44
  }
40
45
  let raw;
41
46
  try {
@@ -55,7 +60,7 @@ async function sha256Hex(input) {
55
60
  const d = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
56
61
  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
57
62
  }
58
- async function api(base, method, path, { body, kp, bearer, query, signQuery } = {}) {
63
+ async function api(base, method, path, { body, kp, apiKey, bearer, query, signQuery } = {}) {
59
64
  let qs = "";
60
65
  if (query) {
61
66
  const params = new URLSearchParams();
@@ -71,6 +76,8 @@ async function api(base, method, path, { body, kp, bearer, query, signQuery } =
71
76
  const headers = {};
72
77
  if (sentRaw) headers["content-type"] = "application/json";
73
78
  if (bearer) headers.Authorization = `Bearer ${bearer}`;
79
+ if (kp && apiKey) die("pass either a keypair or an apiKey to api(), never both");
80
+ if (apiKey) headers["X-API-Key"] = apiKey;
74
81
  if (kp) {
75
82
  const timestamp = String(Math.floor(Date.now() / 1e3));
76
83
  const nonce = [...nacl.randomBytes(12)].map((b) => b.toString(16).padStart(2, "0")).join("");
@@ -294,7 +301,7 @@ function coerce(raw, type) {
294
301
  }
295
302
 
296
303
  // src/version.ts
297
- var VERSION = "0.2.1";
304
+ var VERSION = "0.3.0";
298
305
  export {
299
306
  MAX_BUNDLE_BYTES,
300
307
  VERSION,
@@ -6,5 +6,27 @@
6
6
  * reduced one — and an agent can drive it identically.
7
7
  */
8
8
  import { type Flags } from './auth.js';
9
- export declare const HELP = "singularity processors \u2014 deploy loops we host and run\n\n init [slug] scaffold processor.json + processor.js here\n configure interactive setup: keypair, defaults\n deploy create it (prints the invoke token ONCE)\n update push new code or manifest\n run '{\"n\":10}' invoke and print the output\n run --get '{\"n\":10}' invoke over GET (for methods: [\"GET\"] processors)\n call -i invoke interactively, prompted per input field\n schema [slug] the input/output schema buyers and agents see\n list your processors\n search [query] the public catalogue\n logs [slug] recent runs and failure rate\n logs --follow stream new runs as they happen\n revenue sales and compute spend across everything you own\n earnings [slug] the same, for one processor\n env list | unset KEY which secrets are set; clear one\n secrets KEY=value ... set secret values (KEY= also clears)\n pause | resume stop or restart traffic, keeping the slug\n publish | unpublish list or unlist publicly (instant, no review)\n rotate new invoke token, the old one stops working\n delete --yes soft delete (the slug is never reusable)\n\n --keypair <path> defaults to ~/.config/solana/id.json\n --slug <slug> when not run from a processor directory\n --json machine-readable output, for scripts and agents\n --bundle bundle with esbuild: imports and npm packages\n --entry <file> bundle entry (default: the manifest's $code)";
9
+ export declare function resolveBase(flags: Flags): string;
10
+ export declare const HELP = "singularity processors \u2014 deploy loops we host and run\n\n init [slug] scaffold processor.json + processor.js here\n configure interactive setup: keypair, defaults\n deploy create it (prints the invoke token ONCE)\n update push new code or manifest\n run '{\"n\":10}' invoke and print the output\n run --get '{\"n\":10}' invoke over GET (for methods: [\"GET\"] processors)\n call -i invoke interactively, prompted per input field\n schema [slug] the input/output schema buyers and agents see\n list your processors\n search [query] the public catalogue\n logs [slug] recent runs and failure rate\n logs --follow stream new runs as they happen\n revenue sales and compute spend across everything you own\n earnings [slug] the same, for one processor\n env list | unset KEY which secrets are set; clear one\n secrets KEY=value ... set secret values (KEY= also clears)\n pause | resume stop or restart traffic, keeping the slug\n publish | unpublish list or unlist publicly (instant, no review)\n rotate new invoke token, the old one stops working\n delete --yes soft delete (the slug is never reusable)\n\n --keypair <path> defaults to ~/.config/solana/id.json\n --slug <slug> when not run from a processor directory\n --json machine-readable output, for scripts and agents\n --bundle bundle with esbuild: imports and npm packages\n --entry <file> bundle entry (default: the manifest's $code)\n\nGetting paid. Buyers pay YOU directly \u2014 we never hold the money and take no cut. By default that\nis USDC on Solana at your signing wallet. To be paid on more than one chain, add a \"payout\" block\nto processor.json:\n\n \"payout\": {\n \"solana\": \"<base58 wallet>\", USDC\n \"base\": \"0x\u2026\", USDC\n \"robinhood\": \"0x\u2026\" USDG on Robinhood Chain\n }\n\nOne price_usd covers all three (every asset is 6-decimal), and buyers pick a chain from the 402.\nName only the chains you want: a chain you leave out is never offered. Check each address twice \u2014\na payment cannot be reversed.";
11
+ /**
12
+ * The chains a buyer can pay on. USDC on Solana and Base, USDG on Robinhood Chain — all three are
13
+ * 6-decimal stablecoins, so ONE `price_usd` is the price everywhere with no conversion.
14
+ */
15
+ export type PayoutChain = 'solana' | 'base' | 'robinhood';
16
+ /**
17
+ * Check a payout address BEFORE it is deployed.
18
+ *
19
+ * SHAPE ONLY, and the limit is deliberate. The server validates these too, including the EIP-55
20
+ * checksum, and its check is the one that counts. This one exists because the CLI is where a human
21
+ * pastes an address, and catching "that is not a Solana address" without a round trip is worth a few
22
+ * lines. One wrong character sends every sale for the life of the processor somewhere nobody controls.
23
+ *
24
+ * EIP-55 IS NOT VERIFIED HERE, on purpose: it needs keccak256, and adding a hash implementation — or a
25
+ * dependency — to a CLI that people hand a Solana keypair to costs more than it saves. Deploy rejects a
26
+ * bad checksum and names the address it thinks you meant.
27
+ *
28
+ * NOTHING IS CASE-FOLDED. base58 is case-sensitive, so a lowercased Solana address is a DIFFERENT
29
+ * account that still looks valid; and an EVM address's case IS its checksum.
30
+ */
31
+ export declare function checkPayoutAddress(chain: PayoutChain, value: unknown): string | null;
10
32
  export declare function run(words: string[], flags: Flags): Promise<void>;
package/dist/version.d.ts CHANGED
@@ -8,4 +8,4 @@
8
8
  *
9
9
  * Kept in sync with package.json by the release workflow, which is the only thing that bumps either.
10
10
  */
11
- export declare const VERSION = "0.2.1";
11
+ export declare const VERSION = "0.3.0";
package/package.json CHANGED
@@ -1,78 +1,78 @@
1
1
  {
2
- "name": "@singularity-layer/cli",
3
- "version": "0.2.1",
4
- "description": "Singularity developer CLI \u2014 deploy paid endpoints (Processors) on the Singularity Cloud Network",
5
- "type": "module",
6
- "bin": {
7
- "singularity": "./dist/cli.js"
8
- },
9
- "main": "./dist/index.js",
10
- "types": "./dist/index.d.ts",
11
- "exports": {
12
- ".": {
13
- "types": "./dist/index.d.ts",
14
- "import": "./dist/index.js"
15
- }
16
- },
17
- "files": [
18
- "dist",
19
- "README.md",
20
- "LICENSE"
21
- ],
22
- "engines": {
23
- "node": ">=20"
24
- },
25
- "scripts": {
26
- "build": "node build.mjs",
27
- "test": "vitest run",
28
- "typecheck": "tsc --noEmit",
29
- "prepublishOnly": "npm run typecheck && npm test && npm run build"
30
- },
31
- "dependencies": {
32
- "esbuild": "^0.25.0",
33
- "tweetnacl": "^1.0.3"
34
- },
35
- "devDependencies": {
36
- "@types/node": "^22.0.0",
37
- "typescript": "^5.6.0",
38
- "vitest": "^2.1.9"
39
- },
40
- "keywords": [
41
- "singularity",
42
- "processors",
43
- "x402",
44
- "serverless",
45
- "agents",
46
- "solana",
47
- "mcp"
48
- ],
49
- "license": "MIT",
50
- "repository": {
51
- "type": "git",
52
- "url": "git+https://github.com/Singularity-Layer/singularity-cli.git"
53
- },
54
- "//": [
55
- "PACKAGE NAME vs COMMAND NAME are deliberately different. The bare `singularity` name on npm",
56
- "belongs to someone else, so the package is scoped \u2014 matching the rest of the family. The BIN",
57
- "is still `singularity`, so users type what they expect.",
58
- "",
59
- "esbuild is a RUNTIME dependency, not a build-time one: the CLI bundles the publisher's processor",
60
- "for them. That is what makes npm packages and multi-file TypeScript processors possible at all \u2014",
61
- "bundling happens on the publisher's machine, because running `npm install` on our infrastructure",
62
- "would mean executing arbitrary postinstall scripts on a box holding platform credentials.",
63
- "",
64
- "THIS REPO IS PUBLIC ON PURPOSE. People hand this CLI a Solana keypair, so the code that signs with",
65
- "it should be readable, and npm provenance \u2014 which attests the tarball was built from a named commit",
66
- "by the release workflow \u2014 is only available for public sources.",
67
- "",
68
- "This is the DEVELOPER CLI: one command, subcommands per product. It is deliberately NOT:",
69
- " \u2022 `sgl` \u2014 the Rust node-operator daemon. Different audience and runtime, and its",
70
- " releases are hash-allowlisted, so coupling would slow both.",
71
- " \u2022 `sglcode` \u2014 the agentic coding CLI, a product in its own right.",
72
- "The rule that stops sprawl: new capabilities become SUBCOMMANDS here, never new binaries."
73
- ],
74
- "homepage": "https://github.com/Singularity-Layer/singularity-cli#readme",
75
- "bugs": {
76
- "url": "https://github.com/Singularity-Layer/singularity-cli/issues"
2
+ "name": "@singularity-layer/cli",
3
+ "version": "0.3.0",
4
+ "description": "Singularity developer CLI \u2014 deploy paid endpoints (Processors) on the Singularity Cloud Network",
5
+ "type": "module",
6
+ "bin": {
7
+ "singularity": "./dist/cli.js"
8
+ },
9
+ "main": "./dist/index.js",
10
+ "types": "./dist/index.d.ts",
11
+ "exports": {
12
+ ".": {
13
+ "types": "./dist/index.d.ts",
14
+ "import": "./dist/index.js"
77
15
  }
16
+ },
17
+ "files": [
18
+ "dist",
19
+ "README.md",
20
+ "LICENSE"
21
+ ],
22
+ "engines": {
23
+ "node": ">=20"
24
+ },
25
+ "scripts": {
26
+ "build": "node build.mjs",
27
+ "test": "vitest run",
28
+ "typecheck": "tsc --noEmit",
29
+ "prepublishOnly": "npm run typecheck && npm test && npm run build"
30
+ },
31
+ "dependencies": {
32
+ "esbuild": "^0.25.0",
33
+ "tweetnacl": "^1.0.3"
34
+ },
35
+ "devDependencies": {
36
+ "@types/node": "^22.0.0",
37
+ "typescript": "^5.6.0",
38
+ "vitest": "^2.1.9"
39
+ },
40
+ "keywords": [
41
+ "singularity",
42
+ "processors",
43
+ "x402",
44
+ "serverless",
45
+ "agents",
46
+ "solana",
47
+ "mcp"
48
+ ],
49
+ "license": "MIT",
50
+ "repository": {
51
+ "type": "git",
52
+ "url": "git+https://github.com/Singularity-Layer/singularity-cli.git"
53
+ },
54
+ "//": [
55
+ "PACKAGE NAME vs COMMAND NAME are deliberately different. The bare `singularity` name on npm",
56
+ "belongs to someone else, so the package is scoped \u2014 matching the rest of the family. The BIN",
57
+ "is still `singularity`, so users type what they expect.",
58
+ "",
59
+ "esbuild is a RUNTIME dependency, not a build-time one: the CLI bundles the publisher's processor",
60
+ "for them. That is what makes npm packages and multi-file TypeScript processors possible at all \u2014",
61
+ "bundling happens on the publisher's machine, because running `npm install` on our infrastructure",
62
+ "would mean executing arbitrary postinstall scripts on a box holding platform credentials.",
63
+ "",
64
+ "THIS REPO IS PUBLIC ON PURPOSE. People hand this CLI a Solana keypair, so the code that signs with",
65
+ "it should be readable, and npm provenance \u2014 which attests the tarball was built from a named commit",
66
+ "by the release workflow \u2014 is only available for public sources.",
67
+ "",
68
+ "This is the DEVELOPER CLI: one command, subcommands per product. It is deliberately NOT:",
69
+ " \u2022 `sgl` \u2014 the Rust node-operator daemon. Different audience and runtime, and its",
70
+ " releases are hash-allowlisted, so coupling would slow both.",
71
+ " \u2022 `sglcode` \u2014 the agentic coding CLI, a product in its own right.",
72
+ "The rule that stops sprawl: new capabilities become SUBCOMMANDS here, never new binaries."
73
+ ],
74
+ "homepage": "https://github.com/Singularity-Layer/singularity-cli#readme",
75
+ "bugs": {
76
+ "url": "https://github.com/Singularity-Layer/singularity-cli/issues"
77
+ }
78
78
  }