@grok/agent-sdk 0.2.28 → 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.
Files changed (528) hide show
  1. package/AGENTS.md +29 -29
  2. package/dist/bin/agent-serve.d.ts +2 -2
  3. package/dist/bin/agent-serve.js +3 -3
  4. package/dist/channels/pagerduty/api.js +1 -1
  5. package/dist/channels/pagerduty/pagerduty-channel.d.ts +1 -1
  6. package/dist/channels/pagerduty/pagerduty-channel.d.ts.map +1 -1
  7. package/dist/channels/pagerduty/pagerduty-channel.js +1 -1
  8. package/dist/channels/pagerduty/replay.d.ts +1 -1
  9. package/dist/channels/pagerduty/replay.js +4 -4
  10. package/dist/channels/slack/cli-project.js +1 -1
  11. package/dist/docs/404.html +2 -2
  12. package/dist/docs/assets/{app.DF9vlcdn.js → app.BzTUBOAD.js} +4 -4
  13. package/dist/docs/assets/building-with-agents.md.BqJ7AAjG.js +6 -0
  14. package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.BqJ7AAjG.lean.js} +1 -1
  15. package/dist/docs/assets/changelog.md.BWhC6DET.js +1 -0
  16. package/dist/docs/assets/changelog.md.BWhC6DET.lean.js +1 -0
  17. package/dist/docs/assets/chunks/@localSearchIndexroot.CWxwVoCG.js +1 -0
  18. package/dist/docs/assets/chunks/{VPLocalSearchBox.D8OuwKO0.js → VPLocalSearchBox.DsnRlUT5.js} +1 -1
  19. package/dist/docs/assets/chunks/{arc.DCq_TCYV.js → arc.DH8GOhiv.js} +1 -1
  20. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.PWRNTPbk.js → architectureDiagram-Q4EWVU46.9m9ObyuE.js} +1 -1
  21. package/dist/docs/assets/chunks/{baseUniq.BeRPvRUL.js → baseUniq.BXHpx1lE.js} +1 -1
  22. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.BuRmZVSo.js → blockDiagram-DXYQGD6D.xY3EX59q.js} +1 -1
  23. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.7DKSMwuv.js → c4Diagram-AHTNJAMY.DnqgMVgc.js} +1 -1
  24. package/dist/docs/assets/chunks/channel.Cctv0f7X.js +1 -0
  25. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.7VrO9-9i.js → chunk-4BX2VUAB.BjFxK2A3.js} +1 -1
  26. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.CHystNE2.js → chunk-4TB4RGXK.BujS_Spt.js} +1 -1
  27. package/dist/docs/assets/chunks/{chunk-55IACEB6.Nuh9TbTq.js → chunk-55IACEB6.YbTjhdaM.js} +1 -1
  28. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CA0EKugm.js → chunk-EDXVE4YY.DnQ8t4GC.js} +1 -1
  29. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.F9_mp7U8.js → chunk-FMBD7UC4.B67AwAmj.js} +1 -1
  30. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CEU4QfE1.js → chunk-OYMX7WX6.DrZIAFOm.js} +1 -1
  31. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.B8h_x9_i.js → chunk-QZHKN3VN.BLmmydkn.js} +1 -1
  32. package/dist/docs/assets/chunks/{chunk-YZCP3GAM.Btfb-rKg.js → chunk-YZCP3GAM.DaoOfw0O.js} +1 -1
  33. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DU5sqchW.js +1 -0
  34. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DU5sqchW.js +1 -0
  35. package/dist/docs/assets/chunks/clone.B9rdNt6j.js +1 -0
  36. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.DKvc96Wa.js → cose-bilkent-S5V4N54A.DMQuNhM5.js} +1 -1
  37. package/dist/docs/assets/chunks/{dagre-KV5264BT.CMo0cy1b.js → dagre-KV5264BT.CZoGVuUf.js} +1 -1
  38. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.DDgMOQhB.js → diagram-5BDNPKRD.CLt9uOyL.js} +1 -1
  39. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.BdJnoIsU.js → diagram-G4DWMVQ6.DpczEm1G.js} +1 -1
  40. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.oSvhAZaL.js → diagram-MMDJMWI5.D4r13DvJ.js} +1 -1
  41. package/dist/docs/assets/chunks/{diagram-TYMM5635.C9zZLIE-.js → diagram-TYMM5635.CYU9eGFu.js} +1 -1
  42. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.BNhVyccy.js → erDiagram-SMLLAGMA.QA9naWEw.js} +1 -1
  43. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.BEFLLBiU.js → flowDiagram-DWJPFMVM.BbNoVZYd.js} +1 -1
  44. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.BdUzXBgY.js → ganttDiagram-T4ZO3ILL.IHjDoG7r.js} +1 -1
  45. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.Rd3LlOIJ.js → gitGraphDiagram-UUTBAWPF.B21VMdf5.js} +1 -1
  46. package/dist/docs/assets/chunks/{graph.DnJC1GpG.js → graph.DgJ4L-8V.js} +1 -1
  47. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.xv0xntDJ.js → infoDiagram-42DDH7IO.CQjrcthc.js} +1 -1
  48. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.BaGIlviU.js → ishikawaDiagram-UXIWVN3A.D4tPGtVo.js} +1 -1
  49. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.Cof_h0fp.js → journeyDiagram-VCZTEJTY.BD3WaNbQ.js} +1 -1
  50. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.C5GozFuU.js → kanban-definition-6JOO6SKY.Ca0o4Tqz.js} +1 -1
  51. package/dist/docs/assets/chunks/{layout.zc9UShLc.js → layout.DXXqX4MQ.js} +1 -1
  52. package/dist/docs/assets/chunks/{linear.BoqrFVcJ.js → linear.5c61gNw4.js} +1 -1
  53. package/dist/docs/assets/chunks/{min.DwIfr8hG.js → min.B1-NAjHX.js} +1 -1
  54. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.Dkq2yTtp.js → mindmap-definition-QFDTVHPH.BELznv3-.js} +1 -1
  55. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.B4CpTmHK.js → pieDiagram-DEJITSTG.qPzO1mq5.js} +1 -1
  56. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.BqXnFC9C.js → quadrantDiagram-34T5L4WZ.CxIvzbjX.js} +1 -1
  57. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.DhIN2z-E.js → requirementDiagram-MS252O5E.CqA0iJx8.js} +1 -1
  58. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BhxUAmg2.js → sankeyDiagram-XADWPNL6.XRTutBnb.js} +1 -1
  59. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.BqgU7HU-.js → sequenceDiagram-FGHM5R23.E--7bRLQ.js} +1 -1
  60. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.B1BCO18N.js → stateDiagram-FHFEXIEX.C4vGu8zq.js} +1 -1
  61. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ECMu2BdJ.js +1 -0
  62. package/dist/docs/assets/chunks/{theme.oV7rddEz.js → theme.DMj_7q3B.js} +2 -2
  63. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.oRI8UwMC.js → timeline-definition-GMOUNBTQ.C7LgNVAL.js} +1 -1
  64. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.DmuWrIxN.js → vennDiagram-DHZGUBPP.HUwoZcy_.js} +1 -1
  65. package/dist/docs/assets/chunks/{wardley-RL74JXVD.CEBjM5ov.js → wardley-RL74JXVD.BxFEFYZS.js} +1 -1
  66. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.m5zsCOF9.js → wardleyDiagram-NUSXRM2D.B2pSo5rB.js} +1 -1
  67. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.cPN-587n.js → xychartDiagram-5P7HB3ND.NQhMiOOL.js} +1 -1
  68. package/dist/docs/assets/deployment.md.BtqJrHhp.js +31 -0
  69. package/dist/docs/assets/{deployment.md.DDmjAVbg.lean.js → deployment.md.BtqJrHhp.lean.js} +1 -1
  70. package/dist/docs/assets/evals.md.Dne6VRmZ.js +49 -0
  71. package/dist/docs/assets/evals.md.Dne6VRmZ.lean.js +1 -0
  72. package/dist/docs/assets/{guides_agent-to-agent.md.D1D5f6Jc.js → guides_agent-to-agent.md.BcmSqL2z.js} +8 -8
  73. package/dist/docs/assets/guides_agent-to-agent.md.BcmSqL2z.lean.js +1 -0
  74. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.js → guides_bitbucket.md.BiA6ZMFW.js} +27 -27
  75. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.lean.js → guides_bitbucket.md.BiA6ZMFW.lean.js} +1 -1
  76. package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +9 -0
  77. package/dist/docs/assets/{guides_cloud-agents.md.Ceyjv0ul.lean.js → guides_cloud-agents.md.CiXAW6on.lean.js} +1 -1
  78. package/dist/docs/assets/guides_convert-automation.md.BvTxsJ8J.js +26 -0
  79. package/dist/docs/assets/{guides_convert-automation.md.BjraCvok.lean.js → guides_convert-automation.md.BvTxsJ8J.lean.js} +1 -1
  80. package/dist/docs/assets/{guides_github.md.CgN5sNbW.js → guides_github.md.6jiEH7dg.js} +11 -19
  81. package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.6jiEH7dg.lean.js} +1 -1
  82. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.js → guides_gitlab.md.DcKusOcU.js} +63 -73
  83. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.lean.js → guides_gitlab.md.DcKusOcU.lean.js} +1 -1
  84. package/dist/docs/assets/guides_improve.md.o3WOGR7n.js +16 -0
  85. package/dist/docs/assets/{guides_improve.md.BFYtrtLE.lean.js → guides_improve.md.o3WOGR7n.lean.js} +1 -1
  86. package/dist/docs/assets/{guides_jev.md.Ccw4pedT.js → guides_jev.md.DGCzkMUN.js} +20 -60
  87. package/dist/docs/assets/{guides_jev.md.Ccw4pedT.lean.js → guides_jev.md.DGCzkMUN.lean.js} +1 -1
  88. package/dist/docs/assets/{guides_mcp-oauth.md.ekpWOZCC.js → guides_mcp-oauth.md.C-Sx_IPa.js} +3 -5
  89. package/dist/docs/assets/{guides_mcp-oauth.md.ekpWOZCC.lean.js → guides_mcp-oauth.md.C-Sx_IPa.lean.js} +1 -1
  90. package/dist/docs/assets/guides_migrate.md.BbhHYeCr.js +3 -0
  91. package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.BbhHYeCr.lean.js} +1 -1
  92. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.js +26 -0
  93. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.lean.js +1 -0
  94. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.js +61 -0
  95. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.lean.js +1 -0
  96. package/dist/docs/assets/guides_slack.md.BgIGG9ur.js +82 -0
  97. package/dist/docs/assets/{guides_slack.md.BqiGSYGX.lean.js → guides_slack.md.BgIGG9ur.lean.js} +1 -1
  98. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.js → guides_webhooks.md.B5DXt2v1.js} +7 -7
  99. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.lean.js → guides_webhooks.md.B5DXt2v1.lean.js} +1 -1
  100. package/dist/docs/assets/hillclimbing.md.3TkdF79A.js +5 -0
  101. package/dist/docs/assets/hillclimbing.md.3TkdF79A.lean.js +1 -0
  102. package/dist/docs/assets/index.md.DRfaoRCZ.js +20 -0
  103. package/dist/docs/assets/index.md.DRfaoRCZ.lean.js +1 -0
  104. package/dist/docs/assets/quickstart.md.r-oE8nkX.js +113 -0
  105. package/dist/docs/assets/{quickstart.md.DaLk4ZIF.lean.js → quickstart.md.r-oE8nkX.lean.js} +1 -1
  106. package/dist/docs/assets/reference_access.md.C5lblfUC.js +1 -0
  107. package/dist/docs/assets/{reference_access.md.CExlH_mR.lean.js → reference_access.md.C5lblfUC.lean.js} +1 -1
  108. package/dist/docs/assets/reference_agent-config.md.C0Tp_Fk9.js +27 -0
  109. package/dist/docs/assets/{reference_agent-config.md.11E_xe--.lean.js → reference_agent-config.md.C0Tp_Fk9.lean.js} +1 -1
  110. package/dist/docs/assets/reference_artifacts.md.BJpAI7h9.js +17 -0
  111. package/dist/docs/assets/{reference_artifacts.md.C-hKR2hp.lean.js → reference_artifacts.md.BJpAI7h9.lean.js} +1 -1
  112. package/dist/docs/assets/reference_channels.md.CPWOpdsC.js +21 -0
  113. package/dist/docs/assets/{reference_channels.md.DsJfGSBJ.lean.js → reference_channels.md.CPWOpdsC.lean.js} +1 -1
  114. package/dist/docs/assets/reference_cli.md.B8GdpaRj.js +83 -0
  115. package/dist/docs/assets/reference_cli.md.B8GdpaRj.lean.js +1 -0
  116. package/dist/docs/assets/reference_connections.md.DoY4vrDH.js +54 -0
  117. package/dist/docs/assets/{reference_connections.md.BoAotr7_.lean.js → reference_connections.md.DoY4vrDH.lean.js} +1 -1
  118. package/dist/docs/assets/reference_evals.md.DgfUtfIc.js +69 -0
  119. package/dist/docs/assets/{reference_evals.md.DYKjGFi-.lean.js → reference_evals.md.DgfUtfIc.lean.js} +1 -1
  120. package/dist/docs/assets/{reference_extensions.md.pEVj72Xo.js → reference_extensions.md.DHbW6eOf.js} +6 -8
  121. package/dist/docs/assets/{reference_extensions.md.pEVj72Xo.lean.js → reference_extensions.md.DHbW6eOf.lean.js} +1 -1
  122. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.js +39 -0
  123. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.lean.js +1 -0
  124. package/dist/docs/assets/reference_http-api.md.C7Cb0r2J.js +7 -0
  125. package/dist/docs/assets/{reference_http-api.md._RWELr3d.lean.js → reference_http-api.md.C7Cb0r2J.lean.js} +1 -1
  126. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.js +14 -0
  127. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.lean.js +1 -0
  128. package/dist/docs/assets/reference_limits.md.CbdtFr4T.js +8 -0
  129. package/dist/docs/assets/reference_limits.md.CbdtFr4T.lean.js +1 -0
  130. package/dist/docs/assets/reference_memory.md.CdoJISM-.js +3 -0
  131. package/dist/docs/assets/{reference_memory.md.Dd7cyV9V.lean.js → reference_memory.md.CdoJISM-.lean.js} +1 -1
  132. package/dist/docs/assets/reference_playground.md.DIUsRAcy.js +1 -0
  133. package/dist/docs/assets/{reference_playground.md.CQiJk9CM.lean.js → reference_playground.md.DIUsRAcy.lean.js} +1 -1
  134. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.js +26 -0
  135. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.lean.js +1 -0
  136. package/dist/docs/assets/reference_schedules.md.RhQ9ZLo1.js +45 -0
  137. package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.RhQ9ZLo1.lean.js} +1 -1
  138. package/dist/docs/assets/reference_sessions.md.NXVQt9mP.js +22 -0
  139. package/dist/docs/assets/{reference_sessions.md.C7KFhWXV.lean.js → reference_sessions.md.NXVQt9mP.lean.js} +1 -1
  140. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js} +4 -4
  141. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.lean.js → reference_skills.md.DzCPNPkG.lean.js} +1 -1
  142. package/dist/docs/assets/reference_subagents.md.Dvpq2sUu.js +10 -0
  143. package/dist/docs/assets/{reference_subagents.md.CAhvW4yS.lean.js → reference_subagents.md.Dvpq2sUu.lean.js} +1 -1
  144. package/dist/docs/assets/reference_tools.md.B2OaR1Nb.js +62 -0
  145. package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js} +1 -1
  146. package/dist/docs/assets/templates_agentic-owners.md.B6ZmKAzT.js +13 -0
  147. package/dist/docs/assets/{templates_agentic-owners.md.Dh2nDSqg.lean.js → templates_agentic-owners.md.B6ZmKAzT.lean.js} +1 -1
  148. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.js +10 -0
  149. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.lean.js +1 -0
  150. package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +3 -0
  151. package/dist/docs/assets/{troubleshooting.md.AGJ3jDzj.lean.js → troubleshooting.md.DfKKvW1R.lean.js} +1 -1
  152. package/dist/docs/building-with-agents.html +41 -44
  153. package/dist/docs/building-with-agents.md +11 -104
  154. package/dist/docs/changelog.html +37 -37
  155. package/dist/docs/changelog.md +5 -145
  156. package/dist/docs/deployment.html +54 -54
  157. package/dist/docs/deployment.md +86 -265
  158. package/dist/docs/evals.html +52 -71
  159. package/dist/docs/evals.md +33 -127
  160. package/dist/docs/guides/agent-to-agent.html +43 -43
  161. package/dist/docs/guides/agent-to-agent.md +27 -64
  162. package/dist/docs/guides/bitbucket.html +62 -62
  163. package/dist/docs/guides/bitbucket.md +73 -134
  164. package/dist/docs/guides/cloud-agents.html +37 -37
  165. package/dist/docs/guides/cloud-agents.md +23 -53
  166. package/dist/docs/guides/convert-automation.html +39 -56
  167. package/dist/docs/guides/convert-automation.md +31 -115
  168. package/dist/docs/guides/github.html +46 -54
  169. package/dist/docs/guides/github.md +49 -131
  170. package/dist/docs/guides/gitlab.html +98 -108
  171. package/dist/docs/guides/gitlab.md +104 -184
  172. package/dist/docs/guides/improve.html +38 -43
  173. package/dist/docs/guides/improve.md +24 -90
  174. package/dist/docs/guides/jev.html +55 -95
  175. package/dist/docs/guides/jev.md +57 -159
  176. package/dist/docs/guides/mcp-oauth.html +38 -40
  177. package/dist/docs/guides/mcp-oauth.md +34 -69
  178. package/dist/docs/guides/migrate.html +38 -43
  179. package/dist/docs/guides/migrate.md +56 -130
  180. package/dist/docs/guides/opentelemetry.html +41 -43
  181. package/dist/docs/guides/opentelemetry.md +32 -27
  182. package/dist/docs/guides/pagerduty.html +50 -49
  183. package/dist/docs/guides/pagerduty.md +65 -199
  184. package/dist/docs/guides/slack.html +51 -57
  185. package/dist/docs/guides/slack.md +76 -205
  186. package/dist/docs/guides/webhooks.html +42 -42
  187. package/dist/docs/guides/webhooks.md +64 -146
  188. package/dist/docs/hashmap.json +1 -1
  189. package/dist/docs/hillclimbing.html +40 -42
  190. package/dist/docs/hillclimbing.md +40 -102
  191. package/dist/docs/index.html +55 -62
  192. package/dist/docs/index.md +49 -82
  193. package/dist/docs/llms-full.txt +2292 -5830
  194. package/dist/docs/llms.txt +9 -15
  195. package/dist/docs/quickstart.html +96 -153
  196. package/dist/docs/quickstart.md +93 -178
  197. package/dist/docs/reference/access.html +36 -36
  198. package/dist/docs/reference/access.md +7 -12
  199. package/dist/docs/reference/agent-config.html +43 -56
  200. package/dist/docs/reference/agent-config.md +93 -176
  201. package/dist/docs/reference/artifacts.html +38 -39
  202. package/dist/docs/reference/artifacts.md +38 -62
  203. package/dist/docs/reference/channels.html +38 -39
  204. package/dist/docs/reference/channels.md +102 -151
  205. package/dist/docs/reference/cli.html +68 -84
  206. package/dist/docs/reference/cli.md +233 -698
  207. package/dist/docs/reference/connections.html +45 -57
  208. package/dist/docs/reference/connections.md +83 -164
  209. package/dist/docs/reference/evals.html +66 -53
  210. package/dist/docs/reference/evals.md +97 -128
  211. package/dist/docs/reference/extensions.html +41 -43
  212. package/dist/docs/reference/extensions.md +37 -70
  213. package/dist/docs/reference/hooks.html +40 -52
  214. package/dist/docs/reference/hooks.md +62 -133
  215. package/dist/docs/reference/http-api.html +38 -42
  216. package/dist/docs/reference/http-api.md +66 -118
  217. package/dist/docs/reference/instructions.html +39 -39
  218. package/dist/docs/reference/instructions.md +19 -29
  219. package/dist/docs/reference/limits.html +38 -38
  220. package/dist/docs/reference/limits.md +9 -21
  221. package/dist/docs/reference/memory.html +37 -38
  222. package/dist/docs/reference/memory.md +38 -75
  223. package/dist/docs/reference/playground.html +36 -36
  224. package/dist/docs/reference/playground.md +14 -22
  225. package/dist/docs/reference/project-layout.html +49 -48
  226. package/dist/docs/reference/project-layout.md +38 -84
  227. package/dist/docs/reference/schedules.html +46 -48
  228. package/dist/docs/reference/schedules.md +59 -90
  229. package/dist/docs/reference/sessions.html +37 -37
  230. package/dist/docs/reference/sessions.md +66 -113
  231. package/dist/docs/reference/skills.html +39 -39
  232. package/dist/docs/reference/skills.md +11 -31
  233. package/dist/docs/reference/subagents.html +37 -37
  234. package/dist/docs/reference/subagents.md +17 -31
  235. package/dist/docs/reference/tools.html +47 -64
  236. package/dist/docs/reference/tools.md +48 -130
  237. package/dist/docs/templates/agentic-owners.html +38 -38
  238. package/dist/docs/templates/agentic-owners.md +50 -74
  239. package/dist/docs/templates/reviews.html +69 -0
  240. package/dist/docs/templates/reviews.md +71 -0
  241. package/dist/docs/troubleshooting.html +38 -36
  242. package/dist/docs/troubleshooting.md +48 -101
  243. package/dist/evals.d.ts +2 -2
  244. package/dist/extensions/jev/extension.d.ts +12 -2
  245. package/dist/extensions/jev/extension.d.ts.map +1 -1
  246. package/dist/extensions/jev/extension.js +4 -0
  247. package/dist/extensions/jev/lib/evaluate.d.ts +31 -4
  248. package/dist/extensions/jev/lib/evaluate.d.ts.map +1 -1
  249. package/dist/extensions/jev/lib/evaluate.js +18 -4
  250. package/dist/internal/cli/command.d.ts +1 -1
  251. package/dist/internal/cli/command.js +1 -1
  252. package/dist/internal/cli/commands/channels.js +6 -6
  253. package/dist/internal/cli/commands/develop.d.ts.map +1 -1
  254. package/dist/internal/cli/commands/develop.js +23 -14
  255. package/dist/internal/cli/commands/hosted.js +4 -4
  256. package/dist/internal/cli/commands/index.d.ts +1 -1
  257. package/dist/internal/cli/commands/index.d.ts.map +1 -1
  258. package/dist/internal/cli/commands/index.js +1 -1
  259. package/dist/internal/cli/commands/mcp.js +1 -1
  260. package/dist/internal/cli/commands/project.js +4 -4
  261. package/dist/internal/cli/commands/scaffold.d.ts.map +1 -1
  262. package/dist/internal/cli/commands/scaffold.js +9 -6
  263. package/dist/internal/cli/commands/serve.d.ts +1 -1
  264. package/dist/internal/cli/commands/serve.js +5 -5
  265. package/dist/internal/cli/commands/session.d.ts.map +1 -1
  266. package/dist/internal/cli/commands/session.js +12 -7
  267. package/dist/internal/cli/dispatch.d.ts +3 -3
  268. package/dist/internal/cli/dispatch.js +3 -3
  269. package/dist/internal/cli/errors.d.ts +1 -1
  270. package/dist/internal/cli/errors.d.ts.map +1 -1
  271. package/dist/internal/cli/errors.js +1 -1
  272. package/dist/internal/cli/flags.d.ts +2 -2
  273. package/dist/internal/cli/flags.d.ts.map +1 -1
  274. package/dist/internal/cli/flags.js +2 -2
  275. package/dist/internal/cli/help-command.d.ts +1 -1
  276. package/dist/internal/cli/help-command.js +2 -2
  277. package/dist/internal/cli/help.d.ts +7 -7
  278. package/dist/internal/cli/help.d.ts.map +1 -1
  279. package/dist/internal/cli/help.js +8 -8
  280. package/dist/internal/cli-ax.d.ts.map +1 -1
  281. package/dist/internal/cli-ax.js +3 -0
  282. package/dist/internal/cli-convert-automation.d.ts +1 -1
  283. package/dist/internal/cli-convert-automation.js +1 -1
  284. package/dist/internal/cli-deploy.js +1 -1
  285. package/dist/internal/cli-docs.js +1 -1
  286. package/dist/internal/cli-images.js +1 -1
  287. package/dist/internal/cli-migrate.d.ts +1 -1
  288. package/dist/internal/cli-migrate.js +1 -1
  289. package/dist/internal/cli-pagerduty.d.ts +1 -1
  290. package/dist/internal/cli-pagerduty.js +1 -1
  291. package/dist/internal/cli-skills.js +1 -1
  292. package/dist/internal/convert-automation/types.d.ts +1 -1
  293. package/dist/internal/convert-automation/types.js +1 -1
  294. package/dist/internal/cursor/credentials.js +1 -1
  295. package/dist/internal/deploy-client.d.ts +2 -2
  296. package/dist/internal/deploy-client.d.ts.map +1 -1
  297. package/dist/internal/deploy-manifest.d.ts +1 -0
  298. package/dist/internal/deploy-manifest.d.ts.map +1 -1
  299. package/dist/internal/deploy-manifest.js +0 -1
  300. package/dist/internal/discovery/agent-config.d.ts +2 -6
  301. package/dist/internal/discovery/agent-config.d.ts.map +1 -1
  302. package/dist/internal/discovery/agent-config.js +8 -25
  303. package/dist/internal/discovery/agent.d.ts.map +1 -1
  304. package/dist/internal/discovery/agent.js +2 -3
  305. package/dist/internal/discovery/project.d.ts.map +1 -1
  306. package/dist/internal/discovery/project.js +15 -0
  307. package/dist/internal/init-project.d.ts +7 -3
  308. package/dist/internal/init-project.d.ts.map +1 -1
  309. package/dist/internal/init-project.js +60 -12
  310. package/dist/internal/init-scaffold.d.ts +2 -1
  311. package/dist/internal/init-scaffold.d.ts.map +1 -1
  312. package/dist/internal/init-scaffold.js +20 -7
  313. package/dist/internal/peer-connections.js +1 -1
  314. package/dist/internal/reminder-runner.js +1 -1
  315. package/dist/internal/server.d.ts +1 -1
  316. package/dist/internal/session-cost.d.ts +4 -4
  317. package/dist/internal/session-cost.d.ts.map +1 -1
  318. package/dist/internal/session-cost.js +4 -4
  319. package/dist/internal/session-engine.d.ts +1 -1
  320. package/dist/internal/session-engine.js +2 -2
  321. package/dist/internal/shallow-clone.js +1 -1
  322. package/dist/playground/assets/index-D6mVn9og.js +62 -0
  323. package/dist/playground/assets/index-DlALM6gr.css +1 -0
  324. package/dist/playground/index.html +2 -2
  325. package/dist/types.d.ts +9 -22
  326. package/dist/types.d.ts.map +1 -1
  327. package/docs/README.md +49 -82
  328. package/docs/building-with-agents.md +11 -104
  329. package/docs/changelog.md +6 -146
  330. package/docs/deployment.md +86 -265
  331. package/docs/evals.md +34 -128
  332. package/docs/guides/agent-to-agent.md +27 -64
  333. package/docs/guides/bitbucket.md +73 -134
  334. package/docs/guides/cloud-agents.md +23 -53
  335. package/docs/guides/convert-automation.md +31 -115
  336. package/docs/guides/github.md +49 -131
  337. package/docs/guides/gitlab.md +104 -184
  338. package/docs/guides/improve.md +24 -90
  339. package/docs/guides/jev.md +57 -159
  340. package/docs/guides/mcp-oauth.md +34 -69
  341. package/docs/guides/migrate.md +56 -130
  342. package/docs/guides/opentelemetry.md +37 -27
  343. package/docs/guides/pagerduty.md +68 -200
  344. package/docs/guides/slack.md +76 -205
  345. package/docs/guides/webhooks.md +64 -146
  346. package/docs/hillclimbing.md +41 -103
  347. package/docs/quickstart.md +93 -178
  348. package/docs/reference/access.md +7 -12
  349. package/docs/reference/agent-config.md +93 -176
  350. package/docs/reference/artifacts.md +38 -62
  351. package/docs/reference/channels.md +102 -151
  352. package/docs/reference/cli.md +233 -698
  353. package/docs/reference/connections.md +83 -164
  354. package/docs/reference/evals.md +97 -128
  355. package/docs/reference/extensions.md +37 -70
  356. package/docs/reference/hooks.md +61 -132
  357. package/docs/reference/http-api.md +66 -118
  358. package/docs/reference/instructions.md +20 -30
  359. package/docs/reference/limits.md +10 -22
  360. package/docs/reference/memory.md +38 -75
  361. package/docs/reference/playground.md +14 -22
  362. package/docs/reference/project-layout.md +38 -84
  363. package/docs/reference/schedules.md +59 -90
  364. package/docs/reference/sessions.md +66 -113
  365. package/docs/reference/skills.md +12 -32
  366. package/docs/reference/subagents.md +17 -31
  367. package/docs/reference/tools.md +48 -130
  368. package/docs/templates/agentic-owners.md +50 -74
  369. package/docs/templates/reviews.md +76 -0
  370. package/docs/troubleshooting.md +48 -101
  371. package/package.json +3 -9
  372. package/skills/cli/SKILL.md +15 -15
  373. package/skills/create-agent/SKILL.md +20 -19
  374. package/skills/debug/SKILL.md +4 -4
  375. package/skills/deploy/SKILL.md +2 -2
  376. package/skills/evals/SKILL.md +8 -8
  377. package/skills/framework-map/SKILL.md +3 -3
  378. package/skills/github/SKILL.md +7 -7
  379. package/skills/hillclimb/SKILL.md +4 -4
  380. package/skills/mcp-auth/SKILL.md +3 -3
  381. package/skills/migrate-v2/SKILL.md +40 -41
  382. package/skills/otel/SKILL.md +2 -2
  383. package/skills/setup-slack/SKILL.md +8 -8
  384. package/templates/agentic-owners/README.md +5 -5
  385. package/templates/agentic-owners/bot/tools/record_review.ts +1 -1
  386. package/templates/agentic-owners/package.json +1 -1
  387. package/templates/agents-md/README.md +4 -4
  388. package/templates/agents-md/package.json +1 -1
  389. package/templates/code-wiki/README.md +3 -3
  390. package/templates/code-wiki/package.json +1 -1
  391. package/templates/demo/README.md +3 -3
  392. package/templates/demo/package.json +1 -1
  393. package/templates/pr-autofixer/package.json +1 -1
  394. package/templates/security-help/README.md +5 -5
  395. package/templates/security-help/package.json +1 -1
  396. package/templates/security-reviewer/README.md +3 -3
  397. package/templates/security-reviewer/package.json +1 -1
  398. package/templates/thermo-quality-review/README.md +4 -4
  399. package/templates/thermo-quality-review/package.json +1 -1
  400. package/templates/thermo-review/README.md +4 -4
  401. package/templates/thermo-review/package.json +1 -1
  402. package/templates/triage/README.md +3 -3
  403. package/templates/triage/overlays/jira/README.md +3 -3
  404. package/templates/triage/overlays/linear/README.md +3 -3
  405. package/templates/triage/package.json +1 -1
  406. package/dist/docs/assets/building-with-agents.md.Bf1yH2tG.js +0 -9
  407. package/dist/docs/assets/changelog.md.fZ-NNFeJ.js +0 -1
  408. package/dist/docs/assets/changelog.md.fZ-NNFeJ.lean.js +0 -1
  409. package/dist/docs/assets/chunks/@localSearchIndexroot.mfzjiOsL.js +0 -1
  410. package/dist/docs/assets/chunks/channel.goFR5lbe.js +0 -1
  411. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.B2yLtFja.js +0 -1
  412. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.B2yLtFja.js +0 -1
  413. package/dist/docs/assets/chunks/clone.CztV97Wu.js +0 -1
  414. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.CZlVHdDZ.js +0 -1
  415. package/dist/docs/assets/deployment.md.DDmjAVbg.js +0 -31
  416. package/dist/docs/assets/evals.md.OjKb7tNA.js +0 -68
  417. package/dist/docs/assets/evals.md.OjKb7tNA.lean.js +0 -1
  418. package/dist/docs/assets/guides_agent-to-agent.md.D1D5f6Jc.lean.js +0 -1
  419. package/dist/docs/assets/guides_cloud-agents.md.Ceyjv0ul.js +0 -9
  420. package/dist/docs/assets/guides_convert-automation.md.BjraCvok.js +0 -43
  421. package/dist/docs/assets/guides_grokbot-agents.md.D0PpM_Gf.js +0 -15
  422. package/dist/docs/assets/guides_grokbot-agents.md.D0PpM_Gf.lean.js +0 -1
  423. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.js +0 -54
  424. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.lean.js +0 -1
  425. package/dist/docs/assets/guides_improve.md.BFYtrtLE.js +0 -21
  426. package/dist/docs/assets/guides_migrate.md.RS9Eu-Xh.js +0 -8
  427. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.js +0 -28
  428. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.lean.js +0 -1
  429. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.js +0 -60
  430. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.lean.js +0 -1
  431. package/dist/docs/assets/guides_slack.md.BqiGSYGX.js +0 -88
  432. package/dist/docs/assets/hillclimbing.md.By61f3uq.js +0 -7
  433. package/dist/docs/assets/hillclimbing.md.By61f3uq.lean.js +0 -1
  434. package/dist/docs/assets/index.md.CVRjO09Y.js +0 -27
  435. package/dist/docs/assets/index.md.CVRjO09Y.lean.js +0 -1
  436. package/dist/docs/assets/quickstart.md.DaLk4ZIF.js +0 -170
  437. package/dist/docs/assets/reference_access.md.CExlH_mR.js +0 -1
  438. package/dist/docs/assets/reference_agent-config.md.11E_xe--.js +0 -40
  439. package/dist/docs/assets/reference_artifacts.md.C-hKR2hp.js +0 -18
  440. package/dist/docs/assets/reference_channels.md.DsJfGSBJ.js +0 -22
  441. package/dist/docs/assets/reference_cli.md.DQ3dCgmk.js +0 -99
  442. package/dist/docs/assets/reference_cli.md.DQ3dCgmk.lean.js +0 -1
  443. package/dist/docs/assets/reference_connections.md.BoAotr7_.js +0 -66
  444. package/dist/docs/assets/reference_evals.md.DYKjGFi-.js +0 -56
  445. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.js +0 -51
  446. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.lean.js +0 -1
  447. package/dist/docs/assets/reference_http-api.md._RWELr3d.js +0 -11
  448. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.js +0 -14
  449. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.lean.js +0 -1
  450. package/dist/docs/assets/reference_limits.md.Da1HegjB.js +0 -8
  451. package/dist/docs/assets/reference_limits.md.Da1HegjB.lean.js +0 -1
  452. package/dist/docs/assets/reference_memory.md.Dd7cyV9V.js +0 -4
  453. package/dist/docs/assets/reference_playground.md.CQiJk9CM.js +0 -1
  454. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.js +0 -25
  455. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.lean.js +0 -1
  456. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.js +0 -9
  457. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.lean.js +0 -1
  458. package/dist/docs/assets/reference_schedules.md.RC47aFm4.js +0 -47
  459. package/dist/docs/assets/reference_sessions.md.C7KFhWXV.js +0 -22
  460. package/dist/docs/assets/reference_subagents.md.CAhvW4yS.js +0 -10
  461. package/dist/docs/assets/reference_tools.md.DQr7Fnhu.js +0 -79
  462. package/dist/docs/assets/templates_agentic-owners.md.Dh2nDSqg.js +0 -13
  463. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.js +0 -3
  464. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.lean.js +0 -1
  465. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.js +0 -3
  466. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.lean.js +0 -1
  467. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.js +0 -3
  468. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.lean.js +0 -1
  469. package/dist/docs/assets/templates_triage.md.BYWMloV4.js +0 -9
  470. package/dist/docs/assets/templates_triage.md.BYWMloV4.lean.js +0 -1
  471. package/dist/docs/assets/troubleshooting.md.AGJ3jDzj.js +0 -1
  472. package/dist/docs/guides/grokbot-agents.html +0 -74
  473. package/dist/docs/guides/grokbot-agents.md +0 -129
  474. package/dist/docs/guides/hooks.html +0 -113
  475. package/dist/docs/guides/hooks.md +0 -116
  476. package/dist/docs/reference/prompt.html +0 -68
  477. package/dist/docs/reference/prompt.md +0 -47
  478. package/dist/docs/templates/security-reviewer.html +0 -62
  479. package/dist/docs/templates/security-reviewer.md +0 -81
  480. package/dist/docs/templates/thermo-quality-review.html +0 -62
  481. package/dist/docs/templates/thermo-quality-review.md +0 -75
  482. package/dist/docs/templates/thermo-review.html +0 -62
  483. package/dist/docs/templates/thermo-review.md +0 -75
  484. package/dist/docs/templates/triage.html +0 -68
  485. package/dist/docs/templates/triage.md +0 -101
  486. package/dist/extensions/cursor-grokbot-agents/extension.d.ts +0 -71
  487. package/dist/extensions/cursor-grokbot-agents/extension.d.ts.map +0 -1
  488. package/dist/extensions/cursor-grokbot-agents/extension.js +0 -64
  489. package/dist/extensions/cursor-grokbot-agents/lib/agents.d.ts +0 -11
  490. package/dist/extensions/cursor-grokbot-agents/lib/agents.d.ts.map +0 -1
  491. package/dist/extensions/cursor-grokbot-agents/lib/agents.js +0 -31
  492. package/dist/extensions/cursor-grokbot-agents/lib/backend.d.ts +0 -56
  493. package/dist/extensions/cursor-grokbot-agents/lib/backend.d.ts.map +0 -1
  494. package/dist/extensions/cursor-grokbot-agents/lib/backend.js +0 -139
  495. package/dist/extensions/cursor-grokbot-agents/lib/contacts.d.ts +0 -28
  496. package/dist/extensions/cursor-grokbot-agents/lib/contacts.d.ts.map +0 -1
  497. package/dist/extensions/cursor-grokbot-agents/lib/contacts.js +0 -46
  498. package/dist/extensions/cursor-grokbot-agents/lib/conversation.d.ts +0 -53
  499. package/dist/extensions/cursor-grokbot-agents/lib/conversation.d.ts.map +0 -1
  500. package/dist/extensions/cursor-grokbot-agents/lib/conversation.js +0 -186
  501. package/dist/extensions/cursor-grokbot-agents/lib/inputs.d.ts +0 -4
  502. package/dist/extensions/cursor-grokbot-agents/lib/inputs.d.ts.map +0 -1
  503. package/dist/extensions/cursor-grokbot-agents/lib/inputs.js +0 -15
  504. package/dist/extensions/cursor-grokbot-agents/lib/lock.d.ts +0 -12
  505. package/dist/extensions/cursor-grokbot-agents/lib/lock.d.ts.map +0 -1
  506. package/dist/extensions/cursor-grokbot-agents/lib/lock.js +0 -24
  507. package/dist/extensions/cursor-grokbot-agents/skills/consult.md +0 -40
  508. package/dist/extensions/cursor-grokbot-agents/tools/ask.d.ts +0 -4
  509. package/dist/extensions/cursor-grokbot-agents/tools/ask.d.ts.map +0 -1
  510. package/dist/extensions/cursor-grokbot-agents/tools/ask.js +0 -26
  511. package/dist/extensions/cursor-grokbot-agents/tools/check.d.ts +0 -4
  512. package/dist/extensions/cursor-grokbot-agents/tools/check.d.ts.map +0 -1
  513. package/dist/extensions/cursor-grokbot-agents/tools/check.js +0 -21
  514. package/dist/extensions/cursor-grokbot-agents/tools/interrupt.d.ts +0 -4
  515. package/dist/extensions/cursor-grokbot-agents/tools/interrupt.d.ts.map +0 -1
  516. package/dist/extensions/cursor-grokbot-agents/tools/interrupt.js +0 -13
  517. package/dist/extensions/cursor-grokbot-agents/tools/list.d.ts +0 -4
  518. package/dist/extensions/cursor-grokbot-agents/tools/list.d.ts.map +0 -1
  519. package/dist/extensions/cursor-grokbot-agents/tools/list.js +0 -22
  520. package/dist/playground/assets/index-BMpVzZzC.css +0 -1
  521. package/dist/playground/assets/index-_3zz3yh8.js +0 -62
  522. package/docs/guides/grokbot-agents.md +0 -134
  523. package/docs/guides/hooks.md +0 -121
  524. package/docs/reference/prompt.md +0 -52
  525. package/docs/templates/security-reviewer.md +0 -86
  526. package/docs/templates/thermo-quality-review.md +0 -80
  527. package/docs/templates/thermo-review.md +0 -80
  528. package/docs/templates/triage.md +0 -106
@@ -5,30 +5,21 @@ description: "Look up Agent SDK commands, targets, flags, outputs, and exit stat
5
5
 
6
6
  # Agent SDK CLI
7
7
 
8
- The Agent SDK is published as `@grok/agent-sdk` with the `agent-sdk`
9
- CLI.
8
+ The CLI needs Node 22.13 or newer. Run `agent-sdk <command> --help` to see
9
+ every flag for that command.
10
10
 
11
11
  ```text
12
12
  agent-sdk <command>
13
13
  ```
14
14
 
15
- The command catalog below documents the `agent-sdk` binary from
16
- `@grok/agent-sdk`. Run it with Node 22.13 or newer; Bun is not
17
- supported. Commands exit nonzero when validation or a synchronous request fails;
18
- asynchronous commands can exit `0` once work is accepted. Project paths use the
19
- [Agent SDK project layout](./project-layout.md).
15
+ `agent-sdk help --all` prints every command, and
16
+ `agent-sdk help <command> --json` prints one command's flags as JSON.
20
17
 
21
- Install `@grok/agent-sdk` to obtain the binary. Bare `agent-sdk` prints the command
22
- index. `agent-sdk <command> --help` prints one command's help, `agent-sdk help --all`
23
- prints every command, and `agent-sdk help <command> --json` prints one command's
24
- arguments and flags as JSON.
25
-
26
- The `bdk` command remains available.
27
-
28
- Commands are named `agent-sdk <resource> <verb>`, such as `agent-sdk deployment list`,
29
- except for a few workflow verbs (`init`, `dev`, `run`, `eval`, `deploy`, and
30
- others). Older names, such as `agent-sdk deployments` or `agent-sdk secrets set`, still
31
- run for now. Each one prints the new form on stderr.
18
+ Commands are named `agent-sdk <resource> <verb>`, such as
19
+ `agent-sdk deployment list`, apart from workflow verbs such as `init`, `dev`,
20
+ and `deploy`. Older names, such as `agent-sdk deployments` or
21
+ `agent-sdk secrets set`, still run and print the new form on stderr. The `bdk`
22
+ command remains available.
32
23
 
33
24
  ## Command catalog
34
25
 
@@ -39,18 +30,15 @@ run for now. Each one prints the new form on stderr.
39
30
  | `help`, `--help`, `-h` | Print the command index, or one command's help |
40
31
  | [`serve`](#serve) | Serve one or more agents over HTTP |
41
32
  | [`dev`](#dev) | Serve agents with local-development behavior |
42
- | [`docs`](#docs) | Serve the documentation bundled with `@grok/agent-sdk` |
43
- | [`init`](#init) | Scaffold an Agent SDK project, or convert an Automation |
44
- | [`migrate`](#migrate) | Move an early-alpha project to architecture v2 through a pull request |
45
- | [`skills list`](#skills-install) | List the bundled coding-agent skills and their installed versions |
46
- | [`skills install`](#skills-install) | Refresh the bundled coding-agent skills |
47
- | [`info`](#info) | Print the discovered project surface or its deployment manifest |
33
+ | [`docs`](#docs) | Serve the bundled documentation |
34
+ | [`init`](#init) | Scaffold a project, or convert an Automation |
35
+ | [`migrate`](#migrate) | Open a pull request that migrates an early-alpha project |
36
+ | [`skills list`, `skills install`](#skills-install) | List or refresh the bundled coding-agent skills |
37
+ | [`info`](#info) | Print a project's discovered parts or deployment manifest |
48
38
  | [`validate`](#validate) | Check project diagnostics and set the exit status |
49
39
  | [`version`](#version) | Print the installed package version |
50
40
  | [`update`](#update) | Upgrade the installed CLI |
51
- | [`login`](#login-logout-whoami) | Sign the host in to Cursor |
52
- | [`logout`](#login-logout-whoami) | Remove the stored Cursor credential |
53
- | [`whoami`](#login-logout-whoami) | Show the active Cursor credential |
41
+ | [`login`, `logout`, `whoami`](#login-logout-whoami) | Store, remove, or show the Cursor credential |
54
42
 
55
43
  ### Session and eval commands
56
44
 
@@ -61,7 +49,7 @@ run for now. Each one prints the new form on stderr.
61
49
  | [`tool call`](#tool-call) | Call a server tool without a model turn |
62
50
  | [`logs`](#logs) | Follow or dump agent logs |
63
51
  | [`session list`](#session-list) | List sessions, or their costs |
64
- | [`session get`](#session-get) | Inspect a session or a saved trace, or open it in the playground |
52
+ | [`session get`](#session-get) | Inspect a session or a saved trace |
65
53
  | [`session create`](#session-create) | Start or continue a hosted session |
66
54
  | [`eval`](#eval) | Run evals, or list, get, and cancel remote eval batches |
67
55
 
@@ -69,61 +57,42 @@ run for now. Each one prints the new form on stderr.
69
57
 
70
58
  | Command | Contract |
71
59
  | --- | --- |
72
- | [`deploy`](#deploy) | Deploy one or more agents |
73
- | [`deployment list`](#deployment-list) | List deployments |
74
- | [`deployment get`](#deployment-get) | Inspect one deployment |
75
- | [`deployment stop`](#deployment-stop) | Stop a deployment |
76
- | [`deployment start`](#deployment-start) | Start a stopped deployment |
77
- | [`deployment kill`](#deployment-kill) | Stop a deployment, cancel its runs, and lock deploys |
78
- | [`deployment unlock`](#deployment-unlock) | Let a killed deployment deploy again |
79
- | [`deployment cancel-runs`](#deployment-cancel-runs) | Cancel active runs and reminder wakes |
60
+ | [`deploy`](#deploy) | Deploy an agent |
61
+ | [`deployment list`, `deployment get`](#deployment-list) | List deployments, or inspect one |
62
+ | [`deployment stop`, `start`, `kill`, `unlock`, `cancel-runs`, `upgrade`, `rollback`, `delete`, `rotate-token`](#deployment-lifecycle) | Change a deployment's state, release, or alias token |
80
63
  | [`deployment update`](#deployment-update) | Replace a deployment's event repositories |
81
- | [`deployment upgrade`](#deployment-upgrade) | Move a deployment to a release |
82
- | [`deployment rollback`](#deployment-rollback) | Move a deployment to an earlier release |
83
- | [`deployment delete`](#deployment-delete) | Delete a deployment |
84
- | [`deployment rotate-token`](#deployment-rotate-token) | Replace a deployment's alias token |
85
64
  | [`secret`](#secret) | Set, list, or delete deployment secrets |
86
- | [`image`](#image) | Push, list, or delete container images for persistent agents |
87
65
 
88
66
  ### Connection and channel commands
89
67
 
90
68
  | Command | Contract |
91
69
  | --- | --- |
92
- | [`mcp serve`](#mcp) | Proxy an agent's MCP endpoint over stdio |
93
- | [`mcp install`](#mcp) | Add the agent to an MCP client config |
70
+ | [`mcp serve`, `mcp install`](#mcp) | Connect an MCP client to an agent |
94
71
  | [`mcp oauth`](#mcp-oauth) | Authorize an MCP connection |
95
72
  | [`slack`](#slack) | Provision and check Slack channel apps |
96
73
  | [`github`](#github) | Forward, replay, and inspect GitHub webhooks |
97
- | [`gitlab`](#gitlab) | Replay and inspect GitLab webhooks |
98
- | [`bitbucket`](#bitbucket) | Replay and inspect Bitbucket webhooks |
99
- | [`pagerduty`](#pagerduty) | Replay and inspect PagerDuty webhooks |
74
+ | [`gitlab`, `bitbucket`, `pagerduty`](#replay-other-webhooks) | Replay and inspect GitLab, Bitbucket, or PagerDuty webhooks |
100
75
 
101
76
  ## Targets {#choose-a-target}
102
77
 
103
- Commands that send requests support these targets:
104
-
105
78
  | Target | Selection | Commands |
106
79
  | --- | --- | --- |
107
80
  | Ephemeral local server | Omit `--url` and `--prod` | `run`, `tool call`, `eval` |
108
81
  | Running server | Pass `--url <baseUrl>` | `chat`, `run`, `tool call`, `eval`, `logs`, `session list`, `session get`, `mcp serve` |
109
- | Default local server | Omit `--url` and `--prod`; uses `http://127.0.0.1:3000` | `chat`, `logs`, `session list`, `session get` |
110
- | Hosted deployment | Pass `--prod` | `session list`, `session get`, `logs`; `session create` is always hosted |
82
+ | Default local server | Omit `--url` and `--prod` to use `http://127.0.0.1:3000` | `chat`, `logs`, `session list`, `session get` |
83
+ | Hosted deployment | Pass `--prod` | `session list`, `session get`, `logs`. `session create` is always hosted. |
111
84
 
112
- An explicit `--url` must include the slug for a multi-agent server, such as
113
- `http://127.0.0.1:3000/pr-approver`. `--slug` never changes an explicit URL.
114
- `--url` and `--prod` are mutually exclusive.
85
+ A hosted deployment supports only the commands in its row. `chat`, `run`,
86
+ `tool call`, `eval`, `mcp serve`, and `mcp install` exit with a usage error
87
+ when you pass `--prod`. To test a hosted agent, start a turn with
88
+ [`session create`](#session-create) and inspect it with
89
+ [`session get`](#session-get).
115
90
 
116
- | Option | Contract |
117
- | --- | --- |
118
- | `--dir <path>` | Select the project root. The default is the current directory. |
119
- | `--url <baseUrl>` | Use a running agent instead of local project discovery. |
120
- | `--prod` | Use the hosted deployment. `session list`, `session get`, and `logs` accept it; `chat`, `run`, `tool call`, `mcp serve`, and `eval` exit with a usage error. |
121
- | `--slug <slug>` | Select an agent from a multi-agent project or a hosted deployment. Under `--prod`, the default is the `--dir` basename. |
122
- | `--team <id>` | Select a Cursor team. The signed-in account's team is the default. |
123
- | `--api-key <key>` | Override the Cursor credential for commands that authenticate with Cursor. |
124
- | `--bearer-token <token>` | Authenticate to a running server with a bearer token. |
125
- | `--state-root <path>` | Select local state for `serve` and ephemeral `run`, `tool call`, and `eval` targets. Running and `--prod` targets ignore it. |
126
- | `--json` | Print one JSON document on stdout, errors included (`{"error":{"code","message","hint"}}`). Without it, output is text, also when piped. `agent-sdk help` lists the exit codes. |
91
+ `--url` and `--prod` are mutually exclusive. An explicit `--url` must include
92
+ the slug for a multi-agent server, such as `http://127.0.0.1:3000/pr-approver`.
93
+ Otherwise `--slug` picks the agent, and under `--prod` it defaults to the
94
+ `--dir` basename. `--json` prints one JSON document on stdout, including
95
+ errors. Without it, output is text, even when piped.
127
96
 
128
97
  ## Local servers
129
98
 
@@ -144,39 +113,27 @@ agent-sdk serve [--dir <path>] [--port <n>] [--host <host>]
144
113
  [--cursor-events --repo <owner/name>]...
145
114
  ```
146
115
 
147
- | Option | Contract |
148
- | --- | --- |
149
- | `--port <n>` | Listen on this port. The default is `3000`; `0` selects an available port. When an omitted default is occupied, the CLI selects the next port. An occupied explicit port fails with a next-port hint. |
150
- | `--host <host>` | Bind this host. The default is loopback-only `127.0.0.1`. |
151
- | `--mode multi` | Mount projects at `/<slug>/v1/*` and `/<slug>/playground`, with an index at `/`. This is the default. |
152
- | `--mode single` | Mount one project at `/v1/*` and `/playground`. Declared peers are omitted with a warning unless `--peers-url` is set. |
153
- | `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, and enable local playground access. |
154
- | `--state-root <path>` | Store local sessions, streams, workspaces, and channel state here. Keep durable state outside a repository whose rules shouldn't reach agent workspaces. |
155
- | `--bearer-token <secret>` | Require this token on routes without authored authentication. Mutually exclusive with `--allow-anonymous`. |
156
- | `--allow-anonymous` | Admit callers as one anonymous principal. Use it only behind a trusted network boundary. |
157
- | `--allow-anonymous-cursor-github` | Let anonymous callers use sessions with a Cursor account's repository-scoped GitHub credential. Requires an authenticating proxy. |
158
- | `--allow-anonymous-cursor-account-mcp` | Let anonymous callers use Cursor account MCP connections. Requires an authenticating proxy. |
159
- | `--public-url <url>` | Set the externally reachable base URL that turns running off the serve host use for peer MCP and host bridges. It does not expose the server; configure the listener or proxy separately. Local-runtime peers use loopback. |
160
- | `--peers-url <url>` | Resolve declared peers for a single-agent serve through a hosting-provided peer service. Cursor-managed hosting sets this option automatically; a multi-agent serve rejects it. |
161
- | `--no-schedules` | Disable schedule firing outside dev mode. |
162
- | `--no-playground` | Skip the playground. |
163
- | `--no-docs` | Skip the documentation site at `/docs`. |
164
- | `--cursor-events` | Receive SCM events through Cursor. Requires sign-in and one or more repeatable `--repo owner/name` values. |
165
-
166
- Multi-agent slugs start with a letter or digit and contain only letters,
167
- digits, `_`, or `-`. The reserved slugs are `v1`, `playground`, and `docs`.
116
+ `serve` listens on `127.0.0.1:3000`, or the next free port when that one is
117
+ taken. `--mode multi`, the default, mounts each project at `/<slug>/v1/*`, and
118
+ `--mode single` mounts one project at `/v1/*`. `--dev` turns off schedule and
119
+ reminder firing and admits unsigned loopback GitHub deliveries.
120
+
121
+ `--bearer-token` requires a token on routes that don't declare their own
122
+ authentication. `--allow-anonymous` admits every caller as one principal, so
123
+ use it only behind a trusted network boundary. The slugs `v1`, `playground`,
124
+ and `docs` are reserved.
168
125
 
169
126
  ### Develop locally {#dev}
170
127
 
171
- `dev` is `serve --dev` with an optional positional project path:
128
+ `dev` is `serve --dev` with an optional project path:
172
129
 
173
130
  ```text
174
131
  agent-sdk dev
175
- agent-sdk dev ./bdk-pr-reviewer --port 3000
132
+ agent-sdk dev ./agent-sdk-pr-reviewer --port 3000
176
133
  ```
177
134
 
178
- It accepts every `serve` option. Pass at most one positional path, and don't
179
- combine it with a different `--dir`.
135
+ It accepts every `serve` option. Don't combine the path with a different
136
+ `--dir`.
180
137
 
181
138
  ### Serve the docs {#docs}
182
139
 
@@ -184,40 +141,26 @@ combine it with a different `--dir`.
184
141
  agent-sdk docs [--port <n>] [--host 127.0.0.1] [--print]
185
142
  ```
186
143
 
187
- `docs` serves the bundled documentation without an agent project. It uses an
188
- available loopback port by default and stays open until Ctrl-C. `--print`
189
- prints the URL without opening a browser.
144
+ `docs` serves the bundled documentation on a loopback port until you press
145
+ Ctrl-C. `--print` prints the URL without opening a browser.
190
146
 
191
147
  ## Sessions and turns
192
148
 
193
149
  ### Chat with an agent {#chat}
194
150
 
195
- `chat` connects to a running server and never starts an ephemeral one:
196
-
197
151
  ```text
198
152
  agent-sdk chat [--url <baseUrl>] [--message <text>]
199
153
  [--session <id> | --resume] [--continuation-token <token>]
200
154
  [--slug <slug>] [--json] [--text] [--no-color]
201
155
  ```
202
156
 
203
- | Input mode | Behavior |
204
- | --- | --- |
205
- | TTY without `--message` | Open an interactive REPL. |
206
- | TTY with `--message` | Send the message, then keep the REPL open. |
207
- | Non-TTY with `--message` | Send one turn and exit. |
208
- | Non-TTY without `--message` | Read newline-delimited messages until EOF. |
209
- | `--json --message <text>` | Send one turn and print `{ ok, sessionId, continuationToken, trajectory }`. |
210
- | `--json --text --message <text>` | Print a compact trajectory instead of JSON. |
211
-
212
- Use `--session <id>` to reattach a stored session and replay its transcript.
213
- If you omit `--continuation-token`, the CLI looks it up from the target's
214
- session list. `--resume` selects the most recently updated session with a
215
- continuation token. An explicit session ID takes precedence.
157
+ On a TTY, `chat` opens a REPL and sends any `--message` first. Without a TTY, it
158
+ sends `--message` as one turn, or reads newline-delimited messages until EOF.
159
+ `--session <id>` reattaches a stored session, and `--resume` picks the most
160
+ recent one.
216
161
 
217
162
  ### Run turns {#run}
218
163
 
219
- `run` sends messages to an ephemeral local server or a running server:
220
-
221
164
  ```text
222
165
  agent-sdk run [--dir <path>] [--message <text>]...
223
166
  [--messages-file <path>] [--url <baseUrl>]
@@ -226,48 +169,22 @@ agent-sdk run [--dir <path>] [--message <text>]...
226
169
  [--timeout-ms <n>] [--no-stream] [--slug <slug>] [--dry-run]
227
170
  ```
228
171
 
229
- | Option | Contract |
230
- | --- | --- |
231
- | `--message <text>` | Send a user message. Repeat it for a multi-turn run. |
232
- | `--messages-file <path>` | Read a JSON array of strings. File messages run before repeated `--message` values. |
233
- | `--session <id>` | Continue a session on the target. |
234
- | `--continuation-token <token>` | Continue the session selected by `--session` on a running server. |
235
- | `--trace <file>` | Write the raw NDJSON stream to this path. |
236
- | `--no-trace` | Skip the NDJSON trace. |
237
- | `--json` | Print the JSON result instead of the compact trajectory. |
238
- | `--timeout-ms <n>` | Stop waiting after a positive number of milliseconds. There is no default timeout. |
239
- | `--no-stream` | Hide live tool and reply progress on stderr. |
240
- | `--dry-run` | Send nothing. Print the request the run would send. A local run starts no server. |
241
-
242
- Text output is the compact trajectory, with the session ID and trace path on
243
- stderr. `--json` output contains `ok`, `sessionId`, `continuationToken`,
244
- `trace`, `playgroundUrl`, `visualize`, and `trajectory`. The `trace` value
245
- gives the saved path when trace output is enabled.
246
-
247
- For the hosted deployment, use [`session create`](#session-create).
172
+ Repeat `--message` for a multi-turn run. `run` prints the compact trajectory,
173
+ writes an NDJSON trace unless you pass `--no-trace`, and exits `1` when the
174
+ trajectory fails. It has no default timeout.
248
175
 
249
176
  ### Call a tool {#tool-call}
250
177
 
251
- `tool call` invokes a server tool without a model turn:
252
-
253
178
  ```text
254
179
  agent-sdk tool call <tool> [--input <json>]
255
180
  [--dir <path> | --url <baseUrl>]
256
181
  [--session <id>] [--slug <slug>] [--json]
257
182
  ```
258
183
 
259
- `--input` accepts JSON and defaults to `{}`. `--session` uses the session
260
- workspace and records the call on its event stream. The command prints the
261
- tool result (a string as is, anything else as JSON). `--json` prints the
262
- server's full JSON response. The command succeeds only when the HTTP response
263
- succeeds with `ok: true`.
264
-
265
- Hosted deployments don't support `tool call`. Start a model turn with
266
- [`session create`](#session-create) and check it with
267
- [`session get`](#session-get).
268
-
269
- See [Tools](./tools.md#call-a-tool-without-a-model-turn) for validation,
270
- busy-session behavior, and error codes.
184
+ `--input` takes JSON and defaults to `{}`. `--session` runs the tool in that
185
+ session's workspace and records the call. The command exits `1` unless the
186
+ response has `ok: true`. See
187
+ [Tools](./tools.md#call-a-tool-without-a-model-turn) for error codes.
271
188
 
272
189
  ### List sessions {#session-list}
273
190
 
@@ -277,19 +194,10 @@ agent-sdk session list [--url <baseUrl> | --prod] [--since <duration|instant>]
277
194
  [--bearer-token <token>] [--limit <n>] [--page-token <token>] [--json]
278
195
  ```
279
196
 
280
- Text output shows the session ID, channel, mode, turn count, running status,
281
- and update time. `--json` prints `{ items, nextPageToken }`, including
282
- continuation tokens. `--limit` (default 20, at most 100) sets the page size,
283
- and `--page-token` reads the next page.
284
-
285
- With `--prod`, `session list` lists the hosted deployment's most recently
286
- active sessions; `--since 24h` (or an ISO-8601 date or instant) reads back to
287
- that cutoff, up to `--limit` sessions. Check one with
288
- [`session get <sessionId> --prod`](#session-get).
289
-
290
- `--view cost` prints token usage per session and a total from a running
291
- server. Turns saved before cost tracking appear as unpriced. `--json` prints
292
- `{ sessions }`. `--prod` doesn't support this view.
197
+ `--limit` sets the page size, 20 by default and at most 100. With `--prod`,
198
+ it lists the most recently active hosted sessions, and `--since` reads back
199
+ to a cutoff such as `24h` or an ISO-8601 instant.
200
+ `--view cost` works only against a running server.
293
201
 
294
202
  ### Inspect a session {#session-get}
295
203
 
@@ -302,29 +210,12 @@ agent-sdk session get <sessionId> [--url <baseUrl> | --prod]
302
210
  agent-sdk session get --file <file.ndjson> [--json]
303
211
  ```
304
212
 
305
- | Option | Contract |
306
- | --- | --- |
307
- | No option | Print a compact trajectory. |
308
- | `--json` | Print the trajectory object. |
309
- | `--view events` | Print `{ sessionId, events }` with the raw event list. With `--prod`, each tool call is an `actions.requested` or `action.result` event. The tool name is `toolName`. |
310
- | `--view cost` | Print per-turn token usage and estimated cost from a running server. `--prod` doesn't support it. |
311
- | `--trace <file.ndjson>` | Write the raw NDJSON trace instead of printing it. Not available with `--prod`. |
312
- | `--file <file.ndjson>` | Read a saved trace (for example from `run --trace`) instead of a server, and print its trajectory. |
313
- | `--web` | Open the session in the playground, or the dashboard playground with `--prod`. `--print` prints the URL only. A running target with credentials that a browser can't send starts a loopback proxy and stays open until Ctrl-C. |
314
-
315
- Use [`chat --session`](#chat) to continue a conversational session on a
316
- local or running server.
317
-
318
- With `--prod`, the command prints the session's hosted executions: one line
319
- per run with its status, duration, and time, followed by that run's log
320
- lines. When the deployment stored process output, a `Process output:` section
321
- prints that output next. `--json` prints `{ sessionId, executions, startLog, ... }`.
322
- `startLog` is the process output, or `null` when none is stored.
323
- `--view events` prints `{ sessionId, events }`. `--trace` isn't available.
324
- While a turn is running, text output also reports the event count and latest
325
- event type and prints `Turn running; runs may lag behind events.` A run can
326
- show `running` with no logs until the turn ends, so a growing event count is
327
- the progress signal.
213
+ `session get` prints a compact trajectory, or raw [events](./sessions.md#stream-events) with `--view events`. `--view cost` and `--trace` work only locally. `--file` reads a saved trace and exits `1` when that trajectory failed, and `--web` opens the session in the playground. For a hosted deployment:
214
+
215
+ ```bash
216
+ agent-sdk session list --prod
217
+ agent-sdk session get <sessionId> --prod --slug <slug> --view events
218
+ ```
328
219
 
329
220
  ### Start a hosted session {#session-create}
330
221
 
@@ -334,23 +225,14 @@ agent-sdk session create --message <text> [--session <ses_...>]
334
225
  [--read-only] [--as-of <instant>] [--component <key>] [--dry-run] [--json]
335
226
  ```
336
227
 
337
- | Option | Contract |
338
- | --- | --- |
339
- | `--message <text>` | The message to send. Exactly one. |
340
- | `--session <ses_...>` | Continue a hosted session that `session create` started. Slack, SCM, and custom-route sessions can't be continued this way. |
341
- | `--wait` | Poll the delivery until it names the session, then print it. Exit `3` (`pending`) when `--timeout-ms` (default 120000) passes first. A skipped or failed delivery exits `1`. |
342
- | `--read-only` | Run read tools and stub write tools. |
343
- | `--as-of <instant>` | Freeze the session's clock at an ISO-8601 instant with a timezone, such as `2026-08-31T12:00:00Z`. |
344
- | `--component <key>` | Wake a named component instead of the deployment's default. A continued session must belong to that component. |
345
- | `--dry-run` | Send nothing. Print the request it would send. |
346
-
347
- Without `--wait`, the command returns as soon as the deployment accepts the
348
- turn and exits `0` before the turn outcome is known. It prints the delivery
349
- ID, the session ID when known, and the session mode. `--json` prints
350
- `deliveryId`, `workflowId`, `sessionMode`, and `sessionId` when known, plus
351
- `dryRun` and `asOf` when set. A fresh start has no `sessionId` until the turn
352
- starts; a continuation echoes the `--session` value. See
353
- [Verify a hosted turn](../deployment.md#verify-a-hosted-turn).
228
+ `session create` sends one `--message` to the hosted deployment. Without
229
+ `--wait`, it exits `0` once the deployment accepts the turn, before a new
230
+ session has an ID. `--wait` polls until the session starts. It exits `3` when
231
+ `--timeout-ms` passes first and `1` when the delivery is skipped or fails.
232
+
233
+ `--session` continues a session that `session create` started. `--read-only`
234
+ stubs write tools, and `--as-of` freezes the session's clock at an ISO-8601
235
+ instant. See [Verify a hosted turn](../deployment.md#verify-a-hosted-turn).
354
236
 
355
237
  ### Follow logs {#logs}
356
238
 
@@ -359,68 +241,44 @@ agent-sdk logs [sessionId] [--url <baseUrl> | --prod]
359
241
  [--session <sessionId>] [--slug <slug>] [--team <id>] [--once] [--json]
360
242
  ```
361
243
 
362
- The command follows logs until Ctrl-C. `--once` prints the current buffer and
363
- exits; `--json` emits newline-delimited JSON events. With `--prod`, it follows
364
- the output of the hosted deployment's most recent sessions on every channel
365
- and prints a `==> <sessionId> (<channel>) <==` header each time the output
366
- switches sessions. A persistent deployment also prints a `==> process-output <==`
367
- block. That block is the process log the dashboard shows for the deployment.
368
- Pass a session ID, as an argument or with `--session`, to follow only that
369
- session; a session ID requires `--prod`. The session view starts with
370
- `Process output:` for the deployment process log and `Session process output:`
371
- for that session's own process output, and a `tool <name>` line for each tool
372
- call. Hosted log events
373
- carry `sessionId` and `line` rather than `index` and `at`.
244
+ `logs` follows output until Ctrl-C, and `--once` prints the current buffer and
245
+ exits. With `--prod`, it follows the hosted deployment's recent sessions and
246
+ prints a `==> <sessionId> (<channel>) <==` header when the output switches
247
+ sessions. A session ID follows one hosted session and requires `--prod`.
374
248
 
375
249
  ## Evals
376
250
 
377
251
  ### Run evals {#eval}
378
252
 
379
- `eval` discovers `evals/**/*.eval.{ts,js}` and runs selected cases:
253
+ `eval` discovers `evals/**/*.eval.{ts,js}` and runs the selected cases:
380
254
 
381
255
  ```text
382
256
  agent-sdk eval [--dir <path>] [evalId...]
383
257
  [--list] [--tag <tag>]... [--json] [--verbose]
384
258
  [--timeout-ms <n>] [--strict] [--max-concurrency <n>]
385
259
  [--junit <path>] [--artifacts <dir> | --no-artifacts]
386
- [--skip-report] [--out <file.json>] [--no-stream]
260
+ [--skip-report] [--no-stream]
387
261
  [--url <baseUrl>] [--no-wait] [--slug <slug>]
388
262
  ```
389
263
 
390
264
  Select an exact case such as `weather/nyc`, a file prefix such as `weather`,
391
- several IDs, or no IDs for every case. Repeat `--tag` for OR matching. To run
392
- an eval whose ID is a subcommand word (`list`, `get`, `cancel`), put it after
393
- `--`, as in `agent-sdk eval -- list`. Projects must provide
394
- `evals/evals.config.{ts,js}` with `maxConcurrency` between 1 and 200.
265
+ several IDs, or none for every case. Put an ID that is also a subcommand word
266
+ after `--`, as in `agent-sdk eval -- list`. The project needs an
267
+ [eval configuration](./evals.md#eval-configuration).
395
268
 
396
- | Option | Contract |
397
- | --- | --- |
398
- | `--list` | List matching cases without running them. `--list --json` prints an array. |
399
- | `--tag <tag>` | Select a tag. Repeat the option for OR matching. |
400
- | `--json` | Print `{ ok, passed, failed, scored, skipped, strict, results }`. |
401
- | `--verbose` | Stream `t.log` lines and reply snippets. |
402
- | `--no-stream` | Hide live progress on stderr. |
403
- | `--strict` | Treat a scored case below its soft threshold as a failure. |
404
- | `--max-concurrency <n>` | Override `maxConcurrency` from the eval config for an ephemeral local run. |
405
- | `--timeout-ms <n>` | Override the per-case timeout. A case timeout takes precedence, followed by this option, the config timeout, and the 180-second default. |
406
- | `--junit <path>` | Write JUnit XML for an ephemeral local run. |
407
- | `--artifacts <dir>` | Select the artifact directory for an ephemeral local run. The default is a timestamped directory under the project's state directory. |
408
- | `--no-artifacts` | Skip artifacts for an ephemeral local run. |
409
- | `--skip-report` | Ignore reporters from eval files and the eval config during an ephemeral local run. |
410
- | `--out <file.json>` | Also write the full result JSON. |
411
- | `--no-wait` | Return after a running server accepts the batch. |
412
-
413
- A running server prints its Eval ID when it accepts the batch.
414
- Use these commands to inspect or cancel it:
269
+ `--strict` fails a scored case below its soft threshold. The command exits `1`
270
+ for failed cases and `2` for invalid options or no matching cases. A running
271
+ server prints an Eval ID when it accepts the batch, and `--no-wait` returns at
272
+ that point. These commands require `--url`:
415
273
 
416
274
  ```text
417
275
  agent-sdk eval list --url <baseUrl> [--limit <n>] [--page-token <token>]
418
- agent-sdk eval get <evalId> --url <baseUrl> [--out <file.json>]
276
+ agent-sdk eval get <evalId> --url <baseUrl>
419
277
  agent-sdk eval cancel <evalId> --url <baseUrl>
420
278
  ```
421
279
 
422
- `eval list` lists recent remote runs. `eval get` exits `3` (`pending`) while
423
- the batch still runs. All three require `--url`.
280
+ `eval get` exits `3` while the batch runs and `1` when it failed or was
281
+ cancelled.
424
282
 
425
283
  ## Projects
426
284
 
@@ -431,45 +289,23 @@ agent-sdk init [directory] [--template <name>] [--var id=value]... [--json] [--d
431
289
  agent-sdk init [directory] --from automation:<url-or-uuid> [--dry-run] [--json]
432
290
  ```
433
291
 
434
- Without a directory, `init` prints the setup guide and changes no files. With
435
- a directory, it preserves existing scaffold files, adds missing files,
436
- installs dependencies, and tries to put `agent-sdk` on `PATH`.
437
-
438
- | Option | Contract |
439
- | --- | --- |
440
- | `--template <name>` | Use a bundled template: `agentic-owners`, `agents-md`, `code-wiki`, `demo`, `security-help`, `security-reviewer`, `thermo-quality-review`, `thermo-review`, `triage-jira`, or `triage-linear`. `triage` selects `triage-linear`. |
441
- | `--var id=value` | Answer a template question without a prompt. Repeat for multiple answers. |
442
- | `--json` | Skip interactive login and skill prompts, then print `{ ok, directory, template, created, skipped, installed, installError, cliOnPath, cliLinkError, next }`. `ok` reflects dependency installation. |
443
- | `--dry-run` | List the files `init` would create. Write and install nothing. |
444
-
445
- On a TTY, templates with questions run their interview before writing files.
446
- `init` also offers to refresh the bundled coding-agent skills and starts login
447
- when the host has no Cursor credential.
292
+ Without a directory, `init` prints the setup guide. With one, it adds missing
293
+ scaffold files, installs dependencies, and tries to put `agent-sdk` on `PATH`.
294
+ On a TTY, it also asks the template's questions and starts login when needed.
448
295
 
449
- `--from grokbot:<recipe.json>` and `--from-grokbot <recipe.json>` exit with
450
- `Grok Bot import was removed.`
296
+ `--template` takes `agentic-owners`, `agents-md`, `code-wiki`, `demo`,
297
+ `security-help`, `security-reviewer`, `thermo-quality-review`, `thermo-review`,
298
+ `triage-jira`, or `triage-linear`. `triage` selects `triage-linear`.
299
+ `--var id=value` answers a template question without a prompt. `--dry-run`
300
+ lists the files without writing them.
451
301
 
452
302
  #### Convert an Automation {#convert-automation}
453
303
 
454
- ```text
455
- agent-sdk init [directory] --from automation:<url-or-uuid> [--dry-run] [--json]
456
- ```
457
-
458
- The input can be a Cursor Automation dashboard URL or its UUID. The output
459
- directory defaults to `./<automation-name>`; a positional directory overrides
460
- it. Generated files don't overwrite
461
- existing paths, and missing scaffold files are added. The following
462
- `npm install` can update lockfiles and run lifecycle scripts from an existing
463
- `package.json`.
464
-
465
- `--json` prints
466
- `{ ok, directory, files, warnings, setupSteps, installed, installError, mcpConnections }`.
467
- Conversion warnings and dependency-install failures remain visible in this
468
- output without failing a completed file conversion. Invalid input,
469
- authentication, export, and file-write failures exit nonzero.
470
-
471
- See [Convert a Cursor Automation](../guides/convert-automation.md) for the
472
- generated project and features that need manual review.
304
+ `--from automation:` takes a Cursor Automation dashboard URL or UUID and
305
+ writes to `./<automation-name>` unless you name a directory. Generated files
306
+ don't overwrite existing paths, but the `npm install` that follows can run
307
+ lifecycle scripts from an existing `package.json`. See
308
+ [Convert a Cursor Automation](../guides/convert-automation.md).
473
309
 
474
310
  ### Migrate an early-alpha project {#migrate}
475
311
 
@@ -478,67 +314,21 @@ agent-sdk migrate [--dir <path>] [--repo <https-url>] [--ref <git-ref>]
478
314
  [--path <agent-path>] [--no-wait] [--json] [--api-key <key>]
479
315
  ```
480
316
 
481
- `migrate` applies only to projects deployed on architecture v1 during the Agent SDK
482
- early alpha. It reads a pushed Git ref, starts a Cursor cloud agent with the
483
- bundled `bdk-migrate-v2` skill, and opens a pull request with the source
484
- changes. The command waits for the pull request by default and never deploys
485
- the project or changes deployment secrets. When it starts an agent, it prints
486
- a checklist for the steps after the first deploy: deploy each agent folder,
487
- create the prod Slack app, unset peer URL secrets, and set secrets a new slug
488
- still needs.
489
-
490
- The command prints `Nothing to migrate.` and exits 0 only when `--dir` shows
491
- no migration work. That check looks for a legacy early-alpha package dependency,
492
- `architecture: "v1"`, `bot/storage.ts` or `agent/storage.ts`,
493
- `runtime: "grokbot"`, a literal SCM credential, a `/v1` continuation selector,
494
- an anonymous reminder, and a `*_MCP_URL` peer connection. When any of those is
495
- present, or a project file cannot be read, the command starts the agent. It
496
- does not read the hosted deployment.
497
-
498
- | Option | Contract |
499
- | --- | --- |
500
- | `--dir <path>` | Select the local Agent SDK project. The default is the current directory. |
501
- | `--repo <https-url>` | Select the source repository. The CLI infers the current checkout's origin when possible. |
502
- | `--ref <git-ref>` | Select the pushed ref for the cloud agent. The CLI infers the current branch when possible. |
503
- | `--path <agent-path>` | Select the project path relative to the repository root. The CLI infers it from `--dir` when possible. |
504
- | `--no-wait` | Print the cloud agent URL and return after the agent starts. |
505
- | `--json` | Print a report with `ok`, `status`, `agentId`, and the cloud agent `url`. A completed migration adds `prUrl` and `checklist`. A run with nothing to migrate uses `status: "current"` and `message` (no agent started) or `summary` (the agent reported it). A blocked or failed migration adds its explanation. |
506
- | `--api-key <key>` | Override the Cursor credential. |
507
-
508
- Credential resolution follows the normal order: `--api-key`,
509
- `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, then
510
- the stored `agent-sdk login` credential. See
511
- [Migrate an early-alpha project](../guides/migrate.md) for detection, pull
512
- request review, and deployment cutover.
317
+ `migrate` applies only to projects that deployed with `architecture: "v1"`
318
+ during the early alpha. It starts a Cursor cloud agent on a pushed Git ref
319
+ with the bundled `bdk-migrate-v2` skill, and the agent opens a pull request
320
+ with the source changes. The command never deploys or changes secrets.
321
+
322
+ With nothing to change, it prints `Nothing to migrate.` and exits `0`, and it exits `1` if the run ends without a pull request. `deploy` refuses a project that sets `architecture: "v1"` and points to `migrate`. See [Migrate an early-alpha project](../guides/migrate.md).
513
323
 
514
324
  ### Install and list coding-agent skills {#skills-install}
515
325
 
516
326
  ```text
517
327
  agent-sdk skills install [--dry-run] [--json]
518
- ```
519
-
520
- The command replaces the installed Agent SDK skills with the package copy and
521
- removes stale bundled skills. `--dry-run` previews the change. `--json` prints
522
- `{ ok, dryRun, directory, firstInstall, skills, removed }`.
523
-
524
- Package installation performs this copy.
525
- Run `agent-sdk skills install` when you need to refresh it.
526
-
527
- Each installed `SKILL.md` records the package release in `metadata.version`.
528
-
529
- ```text
530
328
  agent-sdk skills list [--json [--fields <a,b.c>]] [--limit <n>] [--page-token <token>]
531
329
  ```
532
330
 
533
- `skills list` prints each bundled skill and the version of its installed
534
- copy. `--json` prints `{ items, nextPageToken }`. Each item has `name`,
535
- `description`, `version`, `installedVersion`, and `path`. `installedVersion`
536
- is `null` when the skill is not installed, and `"unknown"` when the installed
537
- copy has no `metadata.version`. When `installedVersion` differs from
538
- `version`, run `agent-sdk skills install`.
539
-
540
- The `bdk-cli` skill holds the rules for agents that run `agent-sdk`: `--json`,
541
- exit codes, `--fields`, `--dry-run`, `--yes`, secrets, and untrusted output.
331
+ Package installation copies the bundled skills, `skills install` replaces the installed copies and removes stale ones, and `skills list` prints each skill's bundled and installed versions. The `bdk-cli` skill teaches agents to run `agent-sdk` safely.
542
332
 
543
333
  ### Inspect a project {#info}
544
334
 
@@ -546,14 +336,9 @@ exit codes, `--fields`, `--dry-run`, `--yes`, secrets, and untrusted output.
546
336
  agent-sdk info [--dir <path>] [--view info|manifest] [--json [--fields <a,b.c>]]
547
337
  ```
548
338
 
549
- Text output lists the model, instructions, tools, skills, extensions,
550
- connections, subagents, channels, schedules, hooks, hosting settings, and
551
- diagnostics. For one unslugged project, `--json` prints its project info
552
- object. For slugged or multi-agent discovery, it prints `{ agents }`.
553
-
554
- `--view manifest` validates one project and prints a summary of its
555
- deployment metadata without a network request. `--json` then prints the full
556
- manifest JSON.
339
+ Text output lists what discovery found, such as tools, channels, and
340
+ diagnostics. `--view manifest` summarizes one project's deployment metadata
341
+ without a network request.
557
342
 
558
343
  ### Validate a project {#validate}
559
344
 
@@ -561,16 +346,11 @@ manifest JSON.
561
346
  agent-sdk validate [--dir <path>]
562
347
  ```
563
348
 
564
- `validate` prints every discovered project's diagnostics and exits nonzero
565
- when any diagnostic has error severity. Use it instead of `info --json` when a
566
- script needs validation status.
567
-
568
- Hosting checks run here too. On architecture v2 (the default), a
569
- `githubChannel` credential or a GitLab or Bitbucket `webhookSecret` written
570
- as a literal or a `() => process.env.NAME` getter is an error whose message
571
- quotes the `{ secretName: "NAME" }` form to use instead. A project that still
572
- sets `architecture: "v1"` gets the same finding as a warning, so run
573
- `validate` before removing the pin to list what the migration must rename.
349
+ `validate` prints every discovered project's diagnostics and exits `1` when
350
+ any diagnostic has error severity. `validate` fails when an SCM webhook secret
351
+ or GitHub credential is a literal or a getter, and the error message shows the
352
+ `{ secretName }` form to use. A project that still sets `architecture: "v1"`
353
+ gets the same finding as a warning.
574
354
 
575
355
  ## Credentials and versions
576
356
 
@@ -582,49 +362,38 @@ agent-sdk whoami [--json]
582
362
  agent-sdk logout
583
363
  ```
584
364
 
585
- | Command | Contract |
586
- | --- | --- |
587
- | `login` | Use a supplied API key, or open browser sign-in and store the resulting dashboard-revocable key in the CLI config directory. `--key-name` labels a browser-created key. |
588
- | `whoami` | Show the active credential and its source. `--json` returns the same identity as JSON. |
589
- | `logout` | Remove the stored credential file. It doesn't revoke the API key; revoke the key in the Cursor dashboard. |
365
+ `login` stores a supplied API key, or opens browser sign-in and stores the key
366
+ it creates. `whoami` shows the active credential and its source. `logout`
367
+ removes the stored credential but doesn't revoke the key, so revoke it in the
368
+ Cursor dashboard.
590
369
 
591
370
  ### Print the version {#version}
592
371
 
593
372
  ```text
594
373
  agent-sdk version [--json]
595
374
  agent-sdk --version
596
- agent-sdk -V
597
375
  ```
598
376
 
599
- Text output is the version number. `--json` prints
600
- `{ name, version }`.
601
-
602
377
  ### Update the CLI {#update}
603
378
 
604
379
  ```text
605
380
  agent-sdk update
606
381
  ```
607
382
 
608
- `update` checks npm's `latest` tag and upgrades a recognized global or project
609
- install with its package manager. If it can't identify an installed copy, it
610
- prints a manual upgrade command instead.
611
-
612
- Published installs check for updates at most once every 24 hours. Set
613
- `AGENT_SERVE_NO_UPDATE_CHECK`, `NO_UPDATE_NOTIFIER`, or `CI` to disable the
614
- automatic warning.
383
+ `update` upgrades a recognized global or project install to npm's `latest`
384
+ tag, or prints a manual upgrade command. Published installs check for updates
385
+ daily unless an [update-check variable](#environment-variables) is set.
615
386
 
616
387
  ## Managed hosting
617
388
 
618
- Every command here that changes a deployment takes `--dry-run`. It runs the
619
- reads (sign-in, team, and deployment checks), then stops at the first request
620
- that would change state and prints that request, with secret values
621
- redacted. Nothing is sent, and the command exits `0`.
389
+ Every command here that changes a deployment takes `--dry-run`, which runs
390
+ the reads, stops at the first change, prints that request with secrets
391
+ redacted, and exits `0`.
622
392
 
623
- `deployment kill`, `deployment cancel-runs`, `deployment delete`,
624
- `deployment rotate-token`, `secret delete`, `image delete`, and
625
- `slack destroy` cannot be undone. On a terminal they ask you to type the
626
- slug or name. Without a terminal, as when an agent runs them, they exit `2`
627
- unless you pass `--yes`.
393
+ `secret delete`, `image delete`, `slack destroy`, and the `deployment`
394
+ commands marked No in the [lifecycle table](#deployment-lifecycle) can't be
395
+ undone. On a terminal they ask you to type the slug or name, and a mismatch
396
+ exits `1`. Without a terminal, they exit `2` unless you pass `--yes`.
628
397
 
629
398
  ### Deploy agents {#deploy}
630
399
 
@@ -634,113 +403,53 @@ agent-sdk deploy [--dir <path>] [--slug <slug> | --all] [--team <id>]
634
403
  [--cursor-events-repo <repo>]... [--no-wait] [--json]
635
404
  ```
636
405
 
637
- Managed hosting requires a team with agent hosting enabled. A team
638
- service-account API key with agent access can deploy.
406
+ Deploying needs a team with agent hosting turned on, and a team service-account key with agent access can deploy. The CLI infers `--repo`, `--ref`, and `--path` from the current checkout, and the repository must use HTTPS.
639
407
 
640
- | Option | Contract |
641
- | --- | --- |
642
- | `--slug <slug>` | Select one project and set its deployment slug. Under a folder of several agents, this deploys that one agent. |
643
- | `--all` | Deploy every child under a folder of several agents. For a folder of v2 agents, print one deploy command for each agent. |
644
- | `--team <id>` | Select the Cursor team. |
645
- | `--repo <https-url>` | Set the source repository. The CLI infers it from the current checkout when possible. HTTPS is required. |
646
- | `--ref <git-ref>` | Set the source Git ref. The CLI infers the current branch when possible. |
647
- | `--path <agent-path>` | Set the project path relative to the repository root. |
648
- | `--cursor-events-repo <repo>` | Watch a repository's Cursor events. Write `owner/name` for GitHub and Origin, `gitlab.com/<group>/<project>` for GitLab (subgroups allowed), or `bitbucket.org/<workspace>/<repo>` for Bitbucket. Repeat the flag for each repository; the repositories you pass replace the previous list. Without the flag, the deployment watches its GitHub source repository. |
649
- | `--no-wait` | Return after the deployment request is accepted. |
650
- | `--json` | Print one object for one target or an array for multiple targets. |
651
-
652
- Deployment slugs contain lowercase letters, digits, `_`, or `-`, start with a
653
- letter or digit, and have at most 64 characters. Egress entries are lowercase
654
- hostnames with an alphabetic top-level domain; one leading `*.` wildcard is
655
- allowed, or a trailing `:port` for a protocol that is not HTTPS, with at most
656
- 64 entries.
657
-
658
- By default, `deploy` waits until the deployment is running and exits nonzero
659
- if it reaches a failed state. A first deployment can return an alias token
660
- once. Store it as a secret and send it as `X-Agent-Alias-Token` when calling
661
- the stable alias URL.
662
-
663
- When the team egress policy blocks a host, `deploy` exits nonzero and prints
664
- `Error: agent-sdk deploy blocked.` The message names each blocked host, the team
665
- egress mode, and two fixes: add the hosts to the team egress list, or remove
666
- them from `hosting.egressDomains` and deploy again. The running bot does not
667
- change.
668
-
669
- An agent that sets `architecture: "v1"` does not deploy: `deploy` exits
670
- nonzero and tells you to run [`migrate`](#migrate) first.
671
-
672
- ### List deployments {#deployment-list}
408
+ `deploy` deploys one agent. On a folder of several agents, pass `--slug` to
409
+ pick one. `--all`, or picking several agents, prints one
410
+ `agent-sdk deploy --dir` command per agent and exits `1`.
673
411
 
674
- ```text
675
- agent-sdk deployment list [--team <id>] [--limit <n>] [--page-token <token>]
676
- [--json [--fields <a,b.c>]]
677
- ```
412
+ `--cursor-events-repo` sets the repositories whose Cursor events the
413
+ deployment receives. Write `owner/name` for GitHub,
414
+ `gitlab.com/<group>/<project>` for GitLab, or
415
+ `bitbucket.org/<workspace>/<repo>` for Bitbucket. A GitLab path can include
416
+ subgroups. Repeat the flag once per repository. Each deploy replaces the whole list. Without the flag, the deployment watches its GitHub
417
+ source repository.
678
418
 
679
- Text output shows slug, status, and update time. `--json` prints
680
- `{ items, nextPageToken }`. `--limit` (default 20, at most 100) sets the page
681
- size, and `--page-token` reads the next page. An empty list succeeds.
419
+ `deploy` waits until the deployment runs and exits nonzero if it fails, unless
420
+ you pass `--no-wait`. The first deploy of a slug can print an alias token
421
+ once. Slugs use lowercase letters, digits, `_`, and `-`, start with a letter
422
+ or digit, and have at most 64 characters. See [Deployment](../deployment.md)
423
+ for egress hosts and the alias token.
682
424
 
683
- ### Inspect a deployment {#deployment-get}
425
+ ### Inspect deployments {#deployment-list}
684
426
 
685
427
  ```text
428
+ agent-sdk deployment list [--team <id>] [--limit <n>] [--page-token <token>]
429
+ [--json [--fields <a,b.c>]]
686
430
  agent-sdk deployment get <slug> [--team <id>] [--json [--fields <a,b.c>]] [--web]
687
431
  ```
688
432
 
689
- Text output includes status, release, watched repositories, routes, secret
690
- names, and the latest error. `--web` opens the deployment's page in the
691
- dashboard. A deployment still on architecture v1 shows its status with
692
- `architecture: v1` and the [`migrate`](#migrate) steps; `deployment stop` and
693
- `deployment delete` also still accept it.
694
-
695
- ### Stop a deployment {#deployment-stop}
696
-
697
- ```text
698
- agent-sdk deployment stop <slug> [--team <id>] [--no-wait] [--cancel-runs] [--json]
699
- ```
700
-
701
- The command waits for `stopped` by default. `--no-wait` returns after the
702
- request is accepted. `--cancel-runs` also requests cancellation of active
703
- runs and reminder wakes.
704
-
705
- ### Start a deployment {#deployment-start}
706
-
707
- ```text
708
- agent-sdk deployment start <slug> [--team <id>] [--json]
709
- ```
710
-
711
- `deployment start` resumes a stopped deployment. It doesn't remove the
712
- deploy lock that [`deployment kill`](#deployment-kill) sets.
713
-
714
- ### Kill a deployment {#deployment-kill}
715
-
716
- ```text
717
- agent-sdk deployment kill <slug> [--team <id>] [--yes] [--dry-run] [--json]
718
- ```
719
-
720
- Use `deployment kill` in an emergency. It locks deploys of the slug, stops
721
- the deployment, and requests cancellation of its active runs and reminder
722
- wakes. To bring the deployment back, run
723
- [`deployment unlock`](#deployment-unlock) and then
724
- [`deployment start`](#deployment-start).
433
+ `deployment list` shows each deployment's slug, status, and update time, and `deployment get` adds the release, watched repositories, routes, secret names, and latest error. `--web` opens the deployment in [Deployed Agents](https://cursor.com/dashboard/deployed-agents), and an early-alpha deployment shows the steps to migrate it.
725
434
 
726
- ### Unlock deploys {#deployment-unlock}
435
+ ### Change a deployment {#deployment-lifecycle}
727
436
 
728
437
  ```text
729
- agent-sdk deployment unlock <slug> [--team <id>] [--json]
438
+ agent-sdk deployment <command> <slug> [--team <id>] [--json] [--dry-run]
730
439
  ```
731
440
 
732
- `deployment unlock` removes the lock that `deployment kill` sets, so
733
- `deploy`, `deployment upgrade`, and `deployment rollback` work for the slug
734
- again. It doesn't resume traffic; run `deployment start` for that.
735
-
736
- ### Cancel active runs {#deployment-cancel-runs}
737
-
738
- ```text
739
- agent-sdk deployment cancel-runs <slug> [--team <id>] [--yes] [--dry-run] [--json]
740
- ```
741
-
742
- The command requests cancellation for a deployment's active runs and reminder
743
- wakes. It exits nonzero if any cancellation request fails to start.
441
+ | Command | What it does | Undoable? |
442
+ | --- | --- | --- |
443
+ | `stop` | Stop the deployment. `--cancel-runs` also cancels active runs and reminder wakes. | Yes |
444
+ | `start` | Resume a stopped deployment. A kill lock stays. | Yes |
445
+ | `kill` | Lock deploys, stop the deployment, and cancel its runs and reminder wakes. To recover, run `unlock` and then `start`. | No |
446
+ | `unlock` | Remove the kill lock so deploys, upgrades, and rollbacks work again. Traffic stays stopped. | Yes |
447
+ | `cancel-runs` | Cancel active runs and reminder wakes. | No |
448
+ | `update` | Replace the [event repositories](#deployment-update). | Yes |
449
+ | `upgrade` | Move to a ready release, the newest unless you pass `--release`. | Yes |
450
+ | `rollback` | Move to an earlier ready release, the previous one unless you pass `--release`. | Yes |
451
+ | `delete` | Remove the deployment and free its slug. | No |
452
+ | `rotate-token` | Replace the alias token. The old one stops working at once. | No |
744
453
 
745
454
  ### Replace event repositories {#deployment-update}
746
455
 
@@ -749,48 +458,8 @@ agent-sdk deployment update <slug> (--event-repo <owner/name>... | --no-event-re
749
458
  [--team <id>] [--dry-run] [--json]
750
459
  ```
751
460
 
752
- The supplied repositories replace the deployment's complete event repository
753
- list; they aren't merged with the previous list. `--no-event-repos` clears
754
- the list.
755
-
756
- ### Upgrade a deployment {#deployment-upgrade}
757
-
758
- ```text
759
- agent-sdk deployment upgrade <slug> [--release <id-or-version>]
760
- [--team <id>] [--json]
761
- ```
762
-
763
- `--release` accepts a release ID or version. Omit it to select the newest
764
- ready release. `--json` prints `{ releaseId }`.
765
-
766
- ### Roll back a deployment {#deployment-rollback}
767
-
768
- ```text
769
- agent-sdk deployment rollback <slug> [--release <id-or-version>]
770
- [--team <id>] [--json]
771
- ```
772
-
773
- `deployment rollback` moves the deployment to an earlier ready release without
774
- building a new one. Omit `--release` to select the release before the
775
- current one. `--json` prints `{ releaseId }`.
776
-
777
- ### Delete a deployment {#deployment-delete}
778
-
779
- ```text
780
- agent-sdk deployment delete <slug> [--team <id>] [--no-wait] [--yes] [--dry-run] [--json]
781
- ```
782
-
783
- `deployment delete` removes the deployment and frees its slug. It waits until the
784
- deployment is gone unless `--no-wait` is set.
785
-
786
- ### Rotate an alias token {#deployment-rotate-token}
787
-
788
- ```text
789
- agent-sdk deployment rotate-token <slug> [--team <id>] [--yes] [--dry-run] [--json]
790
- ```
791
-
792
- The old token stops working immediately. The replacement appears once;
793
- `--json` prints `{ aliasToken }`.
461
+ The repositories you pass replace the deployment's whole event repository
462
+ list, and `--no-event-repos` clears it.
794
463
 
795
464
  ### Manage deployment secrets {#secret}
796
465
 
@@ -801,44 +470,15 @@ agent-sdk secret list <slug> [--team <id>] [--limit <n>] [--page-token <token>]
801
470
  agent-sdk secret delete <slug> NAME [--team <id>] [--yes] [--dry-run] [--json]
802
471
  ```
803
472
 
804
- Pass secret names to `set`. On a TTY, the CLI prompts for a hidden value and
805
- ends that value at the first newline. With one name, redirected stdin is the
806
- whole value and one trailing newline is removed, so a PEM private key keeps
807
- its line breaks:
473
+ On a TTY, `secret set` prompts for each hidden value. With one name,
474
+ redirected stdin is the whole value minus one trailing newline, so a PEM key
475
+ keeps its line breaks:
808
476
 
809
477
  ```bash
810
478
  agent-sdk secret set my-bot GITHUB_APP_PRIVATE_KEY < ./app.private-key.pem
811
479
  ```
812
480
 
813
- With several names, provide one line per name. `set` rejects `NAME=VALUE` on
814
- the command line unless `--from-argv` is set, because those values can enter
815
- shell history and captured terminals.
816
-
817
- Names use `UPPER_SNAKE_CASE`, start with a letter, and contain at most 64
818
- characters. Names beginning with `CURSOR_` are reserved. Values contain at
819
- most 4096 bytes, and each deployment holds at most 32 secrets.
820
-
821
- `list` returns names and creation times, never values. JSON output is
822
- `{ secretNames }` for `set`, `{ items, nextPageToken }` for `list`, and
823
- `{ removed }` for `delete`. Changes are available to subsequent hosted work.
824
-
825
- ### Manage container images {#image}
826
-
827
- ```text
828
- agent-sdk image push <local-image> --name <name> [--team <id>] [--json]
829
- agent-sdk image list [--team <id>] [--limit <n>] [--page-token <token>] [--json]
830
- agent-sdk image delete <name> [--team <id>] [--yes] [--dry-run] [--json]
831
- ```
832
-
833
- A persistent agent can run inside a container image that your team pushes
834
- and names in `hosting.image`. `push` needs Docker on your machine. It
835
- checks the local image first: the image must be `linux/amd64` and have
836
- `bash`, `git`, `node` 22.13 or newer, and `npm` on `PATH`. The command
837
- then compresses the image and uploads it under `--name`.
838
-
839
- `list` shows the team's images and how many the team can keep (`--json`:
840
- `{ items, nextPageToken, teamImageLimit }`), and `delete` deletes one image. A deploy pins the image it uses, so after you push a
841
- new image under the same name, deploy again to pick it up.
481
+ With several names, give one line per name. `set` rejects `NAME=VALUE` arguments unless you pass `--from-argv`, because shell history keeps them. Names use `UPPER_SNAKE_CASE`, and the `CURSOR_` prefix is reserved. `secret list` returns names, never values.
842
482
 
843
483
  ## MCP connections
844
484
 
@@ -851,13 +491,10 @@ agent-sdk mcp install --url <baseUrl> [--bearer-token <token>]
851
491
  [--name <server-name>] [--dry-run] [--json]
852
492
  ```
853
493
 
854
- | Command | Contract |
855
- | --- | --- |
856
- | `mcp serve` | Read newline-delimited JSON-RPC from stdin and proxy it to the selected agent's MCP endpoint. stdout is reserved for MCP messages. A target is required. |
857
- | `mcp install` | Add the selected agent to `~/.cursor/mcp.json`. The entry runs `agent-sdk mcp`, which older CLI versions also understand. `--name` sets the server name, `--dry-run` previews the entry, and `--json` prints a machine-readable result. A `--url` entry with `--bearer-token` contains that token; handle printed and written copies as credentials. |
858
-
859
- Hosted deployments don't support `mcp serve` or `mcp install`; both exit with a
860
- usage error when you pass `--prod`.
494
+ `mcp serve` proxies newline-delimited JSON-RPC from stdin to the agent's MCP
495
+ endpoint and reserves stdout for MCP messages. `mcp install` adds the agent to
496
+ `~/.cursor/mcp.json`. An entry made with `--bearer-token` contains that token,
497
+ so treat every printed or written copy as a credential.
861
498
 
862
499
  ### Authorize MCP OAuth {#mcp-oauth}
863
500
 
@@ -867,17 +504,10 @@ agent-sdk mcp oauth <connection> [--dir <path>]
867
504
  ```
868
505
 
869
506
  `<connection>` is the basename under `bot/mcp-connections/` or
870
- `bot/host-connections/`.
871
-
872
- | Connection | Result |
873
- | --- | --- |
874
- | `defineConnection({ url, oauth: true })` | Open a browser PKCE flow and save tokens in `mcp-auth.json` under the CLI config directory. |
875
- | `defineConnection({ cursorAccount: true })` | Exits nonzero and points at the cursor.com dashboard, where you authorize the deployment's connectors. |
876
-
877
- URL-connection tokens are bound to the resource URL; authorize again after
878
- changing it.
879
-
880
- See [Host MCP OAuth](../guides/mcp-oauth.md) for the full setup flow.
507
+ `bot/host-connections/`. A `url` connection with `oauth: true` opens a browser
508
+ PKCE flow and saves tokens bound to that URL, so authorize again after you
509
+ change it. A `cursorAccount` connection exits nonzero and points to the
510
+ cursor.com dashboard. See [Host MCP OAuth](../guides/mcp-oauth.md).
881
511
 
882
512
  ## Channel helpers
883
513
 
@@ -901,24 +531,13 @@ agent-sdk slack doctor [--dir <path>]
901
531
  [--prefix <prefix> | --no-prefix] [--channel <id>]... [--json]
902
532
  ```
903
533
 
904
- | Subcommand | Contract |
905
- | --- | --- |
906
- | `setup` | Print the setup choices without changing files. |
907
- | `create` | Open the signed-in Cursor dashboard wizard, write the resulting token pair to `.env.local`, and run `doctor`. The development app is the default; `--env prod` selects production. A second create overwrites the live app manifest. |
908
- | `destroy` | Delete the provisioned app. Existing local token entries remain but stop working. |
909
- | `icon` | Set an HTTPS or local PNG, JPG, or GIF icon of at most 512 KB. |
910
- | `init --manual` | Write the channel, manifests, Slack CLI project, and setup files for a manually managed app. |
911
- | `manifest` | Generate Slack manifests. `--env` defaults to `both`; with `--dry-run`, select one environment when you need one JSON document. |
912
- | `doctor` | Check both tokens, Socket Mode connectivity, Slack authentication, and any repeatable `--channel` values. |
913
-
914
- The default token prefix is the project directory name normalized to upper
915
- snake case. `--no-prefix` uses `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`.
916
- Channel-post subscriptions are off by default; `--channel-posts` adds message
917
- events for public and private channels as required by
918
- `engagement.channelPosts`.
919
- Multi-agent servers need one token pair per agent.
920
-
921
- See [Slack](../guides/slack.md) for app consent and manual setup.
534
+ `slack create` opens the
535
+ [Deployed Agents](https://cursor.com/dashboard/deployed-agents) wizard, writes
536
+ the token pair to `.env.local`, and runs `doctor`, which checks both tokens and
537
+ Socket Mode. It makes the development app unless you pass `--env prod`. The
538
+ token prefix defaults to the project directory name in upper snake case.
539
+ `--channel-posts` adds the message events that `engagement.channelPosts`
540
+ needs. See [Slack](../guides/slack.md) for manual setup.
922
541
 
923
542
  ### Test GitHub webhooks {#github}
924
543
 
@@ -936,165 +555,81 @@ agent-sdk github events [--dir <path>] [--host <host>] [--port <n>] [--json]
936
555
  agent-sdk github doctor [--install] [--json]
937
556
  ```
938
557
 
939
- | Subcommand | Contract |
940
- | --- | --- |
941
- | `forward` | Forward live deliveries with `gh webhook forward`. The CLI derives URLs and events from discovered channels and can fan out to several matches. |
942
- | `replay` | Read a pull request, synthesize selected webhook payloads, and post them to matching channels. The default event is `pull_request`; `'*'` selects the channel's supported declared events. |
943
- | `events` | List discovered channel URLs and event sets. No channels is a successful empty result. |
944
- | `doctor` | Check the GitHub CLI, its login, and the pinned webhook extension. `--install` installs or repairs the extension. |
945
-
946
- Replay supports `pull_request`, `issue_comment`,
947
- `pull_request_review_comment`, `check_run`, `check_suite`, `workflow_run`, and
948
- `status`. `--dry-run` prints without posting. `--fixtures-dir` writes fixtures and
949
- still posts unless combined with `--dry-run`.
558
+ `forward` sends live deliveries to discovered channels through `gh webhook forward`. It needs repository admin access, or organization owner access for `--org`, and it uses the GitHub CLI's own login, so unset `GITHUB_TOKEN` and `GH_TOKEN` first. `doctor` checks the GitHub CLI and its webhook extension.
950
559
 
951
- Forwarding requires repository admin access, or organization owner access for
952
- `--org`. It uses the GitHub CLI's stored login; unset `GITHUB_TOKEN` and
953
- `GH_TOKEN` before forwarding. Replay needs only pull-request read access.
560
+ `replay` reads a pull request with read access, builds webhook payloads, and
561
+ posts them to matching channels. Its events are `pull_request`, the default,
562
+ `issue_comment`, `pull_request_review_comment`, `check_run`, `check_suite`,
563
+ `workflow_run`, and `status`. `--dry-run` prints the payloads without posting,
564
+ and `--fixtures-dir` also writes them as fixtures. See
565
+ [GitHub](../guides/github.md) for channel setup.
954
566
 
955
- See [GitHub](../guides/github.md) for channel setup and live delivery.
956
-
957
- ### Test GitLab webhooks {#gitlab}
567
+ ### Test GitLab, Bitbucket, and PagerDuty webhooks {#replay-other-webhooks}
958
568
 
959
569
  ```text
960
- agent-sdk gitlab replay <mr-url-or-group/project!N>
961
- [--events a,b,c | '*'] [--action <action>]
962
- [--conclusion <status>] [--comment <body>]
963
- [--dir <path>] [--slug <slug>] [--channel <id>]
964
- [--url <url>] [--host <host>] [--port <n>]
965
- [--secret <secret>] [--dry-run] [--fixtures-dir <dir>] [--json]
966
- agent-sdk gitlab events [--dir <path>] [--host <host>] [--port <n>] [--json]
967
- agent-sdk gitlab forward [--dir <path>] [--host <host>] [--port <n>]
570
+ agent-sdk gitlab replay <mr-url-or-group/project!N> [replay flags]
571
+ agent-sdk bitbucket replay <pr-url-or-workspace/repo#N> [replay flags]
572
+ agent-sdk pagerduty replay [incident-id] [replay flags]
573
+ agent-sdk <gitlab|bitbucket|pagerduty> events [--dir <path>] [--json]
574
+ agent-sdk <gitlab|bitbucket> forward [--dir <path>]
968
575
  ```
969
576
 
970
- | Subcommand | Contract |
971
- | --- | --- |
972
- | `replay` | Read a merge request, synthesize selected webhook payloads, and post them to matching channels. The default event is `merge_request`; `'*'` selects the channel's declared events. |
973
- | `events` | List discovered GitLab channel URLs and object kinds. |
974
- | `forward` | Print the public-hook and tunnel recipe for live deliveries. |
577
+ Replay takes the same flags as `github replay`, including `--fixtures-dir`. `events` lists the discovered channels, and `forward` prints the webhook and tunnel recipe for live deliveries.
975
578
 
976
- Replay supports `merge_request`, `note`, `pipeline`, and `push`. It requires
977
- `GITLAB_TOKEN` with project read access. `--secret` defaults to
978
- `GITLAB_WEBHOOK_SECRET`; `--dry-run` and `--fixtures-dir` follow the GitHub replay
979
- contract.
579
+ | Command | Replay events | Default event | Read credential | `--secret` default |
580
+ | --- | --- | --- | --- | --- |
581
+ | `gitlab replay` | `merge_request`, `note`, `pipeline`, `push` | `merge_request` | `GITLAB_TOKEN` | `GITLAB_WEBHOOK_SECRET` |
582
+ | `bitbucket replay` | `pullrequest:created`, `pullrequest:updated`, `pullrequest:comment_created`, `repo:push`, in Cloud or Data Center format | `pullrequest:created` | `BITBUCKET_TOKEN` | `BITBUCKET_WEBHOOK_SECRET` |
583
+ | `pagerduty replay` | `incident.triggered`, `.acknowledged`, `.annotated`, `.escalated`, `.resolved`, `.reopened` | `incident.triggered` | None | `PAGERDUTY_WEBHOOK_SECRET` |
980
584
 
981
- See [GitLab](../guides/gitlab.md) for channel setup and self-managed hosts.
585
+ PagerDuty replay's incident ID defaults to `PREPLAY1`, and `--comment` is the
586
+ note body for `annotated`. Without a secret, its deliveries are unsigned, and
587
+ `agent-sdk dev` admits them from loopback. See [GitLab](../guides/gitlab.md),
588
+ [Bitbucket](../guides/bitbucket.md), and [PagerDuty](../guides/pagerduty.md)
589
+ for channel setup.
982
590
 
983
- ### Test Bitbucket webhooks {#bitbucket}
591
+ ## Environment variables {#environment-variables}
984
592
 
985
- ```text
986
- agent-sdk bitbucket replay <pr-url-or-workspace/repo#N>
987
- [--events a,b,c | '*'] [--comment <body>]
988
- [--dir <path>] [--slug <slug>] [--channel <id>]
989
- [--url <url>] [--host <host>] [--port <n>]
990
- [--secret <secret>] [--dry-run] [--fixtures-dir <dir>] [--json]
991
- agent-sdk bitbucket events [--dir <path>] [--host <host>] [--port <n>] [--json]
992
- agent-sdk bitbucket forward [--dir <path>] [--host <host>] [--port <n>]
993
- ```
994
-
995
- | Subcommand | Contract |
996
- | --- | --- |
997
- | `replay` | Read a pull request, synthesize webhook payloads in the host's Cloud or Data Center format, and post them to matching channels. |
998
- | `events` | List discovered Bitbucket channel URLs and event keys. |
999
- | `forward` | Print the repository-hook and tunnel recipe for live deliveries. |
1000
-
1001
- Replay supports `pullrequest:created`, `pullrequest:updated`,
1002
- `pullrequest:comment_created`, and `repo:push`, along with their supported Data
1003
- Center forms. It requires `BITBUCKET_TOKEN` with pull-request read access.
1004
- `--secret` defaults to `BITBUCKET_WEBHOOK_SECRET`; `--dry-run` and `--out`
1005
- follow the GitHub replay contract.
1006
-
1007
- See [Bitbucket](../guides/bitbucket.md) for Cloud and Data Center setup.
1008
-
1009
- ### Test PagerDuty webhooks {#pagerduty}
1010
-
1011
- ```text
1012
- agent-sdk pagerduty replay [incident-id]
1013
- [--events a,b,c | '*'] [--comment <body>]
1014
- [--dir <path>] [--slug <slug>] [--channel <id>]
1015
- [--url <url>] [--host <host>] [--port <n>]
1016
- [--secret <secret>] [--dry-run] [--fixtures-dir <dir>] [--json]
1017
- agent-sdk pagerduty events [--dir <path>] [--host <host>] [--port <n>] [--json]
1018
- ```
1019
-
1020
- | Subcommand | Contract |
1021
- | --- | --- |
1022
- | `replay` | Synthesize v3 webhook bodies for one incident and post them, in order, to matching channels. The default event is `incident.triggered`; `'*'` selects every declared event replay supports. |
1023
- | `events` | List discovered PagerDuty channel URLs and event types. |
1024
-
1025
- Replay supports `incident.triggered`, `.acknowledged`, `.annotated`,
1026
- `.escalated`, `.resolved`, and `.reopened`, by full name or by action alone
1027
- (`resolved`). It needs no PagerDuty account. The incident id defaults to
1028
- `PREPLAY1`, and `--comment` is the note body for `annotated`. `--secret`
1029
- defaults to `PAGERDUTY_WEBHOOK_SECRET`, signing with its first line when it
1030
- lists several; without either the deliveries are unsigned, which `agent-sdk dev`
1031
- admits from loopback. `--dry-run` and `--out`
1032
- follow the GitHub replay contract.
1033
-
1034
- See [PagerDuty](../guides/pagerduty.md) for channel setup.
1035
-
1036
- ## Environment variables
1037
-
1038
- Credential resolution follows this order: `--api-key`, `CURSOR_API_KEY`,
1039
- `CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, then the stored login.
593
+ The CLI tries `--api-key`, `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
594
+ `CURSOR_SERVICE_ACCOUNT_KEY`, then the stored `agent-sdk login` credential, in
595
+ that order.
1040
596
 
1041
597
  | Variable | Contract |
1042
598
  | --- | --- |
1043
599
  | `CURSOR_API_KEY` | Cursor credential. |
1044
600
  | `CURSOR_API_KEY_FILE` | Path to a Cursor credential file. |
1045
- | `CURSOR_SERVICE_ACCOUNT_KEY` | Team service-account credential used after the API key and key-file sources. |
601
+ | `CURSOR_SERVICE_ACCOUNT_KEY` | Team service-account credential. |
1046
602
  | `CURSOR_API_BASE_URL` | Backend for login, account, deployment, and event commands. |
1047
- | `CURSOR_BACKEND_URL` | Backend for Agent SDK turns. Set it with `CURSOR_API_BASE_URL` when using a non-default backend. |
1048
- | `AGENT_SERVE_CONFIG_DIR` | Override the CLI config directory for stored credentials and update state. |
1049
- | `AGENT_SERVE_NO_UPDATE_CHECK`, `NO_UPDATE_NOTIFIER`, `CI` | Disable published-version checks when set to a non-empty value other than `0`. |
1050
- | `GITHUB_WEBHOOK_SECRET` | Default signature secret for GitHub forwarding and replay. |
603
+ | `CURSOR_BACKEND_URL` | Backend for agent turns. Set it with `CURSOR_API_BASE_URL` for a non-default backend. |
604
+ | `AGENT_SERVE_CONFIG_DIR` | CLI config directory for stored credentials and update state. |
605
+ | `AGENT_SERVE_NO_UPDATE_CHECK`, `NO_UPDATE_NOTIFIER`, `CI` | Turn off update checks when set to a value other than `0`. |
606
+ | `GITHUB_WEBHOOK_SECRET` | Default secret for GitHub forwarding and replay. |
1051
607
  | `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_INSTALLATION_ID` | GitHub App credentials for outbound API calls. |
1052
- | `GITHUB_TOKEN`, `GH_TOKEN` | Token credentials for outbound GitHub calls. Unset both for `github forward`. |
1053
- | `GITLAB_TOKEN` | Token for GitLab API reads and direct channel calls. |
1054
- | `GITLAB_API_BASE_URL` | Override the GitLab REST base URL for self-managed hosts. |
1055
- | `GITLAB_WEBHOOK_SECRET` | Default GitLab webhook token for replay and channel verification. |
1056
- | `BITBUCKET_TOKEN` | Token for Bitbucket API reads and direct channel calls. |
1057
- | `BITBUCKET_API_BASE_URL` | Override the Bitbucket Data Center REST base URL. |
1058
- | `BITBUCKET_WEBHOOK_SECRET` | Default Bitbucket signing secret for replay and channel verification. |
608
+ | `GITHUB_TOKEN`, `GH_TOKEN` | Tokens for outbound GitHub calls. |
609
+ | `GITLAB_TOKEN`, `GITLAB_WEBHOOK_SECRET` | GitLab API token and default webhook token. |
610
+ | `GITLAB_API_BASE_URL` | GitLab REST base URL for self-managed hosts. |
611
+ | `BITBUCKET_TOKEN`, `BITBUCKET_WEBHOOK_SECRET` | Bitbucket API token and default signing secret. |
612
+ | `BITBUCKET_API_BASE_URL` | Bitbucket Data Center REST base URL. |
1059
613
  | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | Slack tokens for one agent. Multi-agent servers use `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN`. |
1060
614
 
1061
615
  ## Exit status
1062
616
 
1063
- Every command uses one exit code table. `agent-sdk help` prints it, and
1064
- `agent-sdk help --json` includes it as `exitCodes`.
617
+ Every command uses these exit codes, and `agent-sdk help --json` lists them
618
+ as `exitCodes`.
1065
619
 
1066
620
  | Code | Meaning |
1067
621
  | --- | --- |
1068
- | `0` | ok |
1069
- | `1` | failed (also `aborted`, `invalid_argument`, `rate_limited`, `unavailable`) |
1070
- | `2` | usage: bad command, flag, or argument |
1071
- | `3` | pending: the work is still running |
622
+ | `0` | `ok` |
623
+ | `1` | `failed`, `aborted`, `invalid_argument`, `rate_limited`, or `unavailable` |
624
+ | `2` | `usage`, for a bad command, flag, or argument |
625
+ | `3` | `pending`, while the work still runs |
1072
626
  | `4` | `not_found` |
1073
627
  | `5` | `unauthenticated` or `permission_denied` |
1074
628
  | `6` | `conflict` or `failed_precondition` |
1075
629
 
1076
- | Command | Nonzero contract |
1077
- | --- | --- |
1078
- | No command | Print the command index and exit `0`. An unknown command exits `2`. |
1079
- | `run` | For local and running-server trajectories, exit `1` when the trajectory fails. |
1080
- | `tool call` | Exit `1` unless the response succeeds with `ok: true`. |
1081
- | `session get --file` | Exit `1` when the reconstructed trajectory failed. |
1082
- | `session create --wait` | Exit `3` when the delivery names no session before `--timeout-ms`, and `1` when it was skipped or failed. |
1083
- | `eval` | Exit `1` for failed cases, or scored cases below threshold with `--strict`; exit `2` for invalid eval options or an execution with no matching cases. An empty `--list` succeeds. |
1084
- | `eval get` | Exit `3` while the batch runs, `1` when it failed or was cancelled, and `2` for invalid usage. |
1085
- | `chat`, `session get` | Exit `2` for documented option conflicts or missing required input. |
1086
- | `validate` | Exit `1` when any project diagnostic has error severity. |
1087
- | Commands that cannot be undone | Exit `2` without `--yes` when there is no terminal to ask on. Exit `1` (`aborted`) when the typed confirmation does not match. |
1088
- | Any command with `--dry-run` | Exit `0` after printing what it would do, unless a check before the first change fails. |
1089
- | `init --from automation:…` | Exit `1` for invalid input, authentication, export, or file-write failure. Warnings and dependency-install failure don't change a successful conversion exit. |
1090
- | `migrate` | Exit `0` when nothing needs a migration, after starting with `--no-wait`, or after the agent opens a pull request. Exit `1` for invalid input, authentication or agent failure, or a completed run without a pull request. |
1091
- | Other commands | Exit nonzero when validation, authentication, a request, or the requested operation fails. |
1092
-
1093
630
  ## Related
1094
631
 
1095
632
  - [Project layout](./project-layout.md)
1096
633
  - [Sessions, events, and streaming](./sessions.md)
1097
- - [Evals](./evals.md)
1098
- - [HTTP API](./http-api.md)
1099
634
  - [Deployment](../deployment.md)
1100
635
  - [Early-alpha migration](../guides/migrate.md)