autark-cli 0.1.3 → 0.1.5

package/README.md

@@ -18,39 +18,53 @@ autark login send your@email.com
 autark login verify your@email.com --code 123456
 ```
 
-## Use
+## Runbook use
+
+Autark is ID-first. Use `product list` / `context` to discover IDs, then pass IDs for writes. `slug/H01` remains a convenience alias.
 
 ```sh
-# products
-autark product upsert --slug chrome-relay --name "chrome-relay" --tagline "..."
-autark product list
+autark product upsert --slug chrome-relay --name "Chrome Relay" --tagline "..."
+autark product list   # prints slug, visibility, id, name
+autark context chrome-relay
+
+autark hypothesis create --product-id <product_id> --md @./H01.md --code H01 --title "..."
+autark run start --hypothesis-id <hypothesis_id>
+autark log action --run-id <run_id> --channel github --title "..." --url https://github.com/...
+autark run finish --run-id <run_id> --narrative @./narrative.md
+```
 
-# hypotheses
-autark hypothesis create --product chrome-relay --code H01 --md @./H01.md --title "..."
-autark hypothesis status chrome-relay/H01 --status active   # active|inactive|dead
+## Mail use
 
-# runs
-autark run start --hypothesis chrome-relay/H01
-autark run finish --run <run_id> --narrative @./narrative.md
+`autark mail` covers the AgentMail surface Autark needs. It does not require a separate AgentMail CLI login.
 
-# actions (anything the agent did during a run)
-autark log action --run <run_id> --channel email --title "..." \
-  --recipient person@example.com --agentmail-thread-id <thread_id>
-autark log action --run <run_id> --channel github --title "..." --url https://github.com/...
+```sh
+autark mail setup --prefix laksh
 
-# context (full hypothesis state for an agent picking up work)
-autark context chrome-relay/H01
+autark mail send --run-id <run_id> \
+  --to person@example.com \
+  --subject "Subject" \
+  --text @./body.txt
 
-autark me
-autark logout
+autark mail reply --run-id <run_id> --message-id <message_id> --text @./reply.txt
+
+autark mail threads --limit 20
+autark mail thread <thread_id>
+autark mail messages --limit 20
+autark mail message <message_id>
+autark mail raw <message_id>
+autark mail attachment --message-id <message_id> --attachment-id <attachment_id> --out file.bin
 ```
 
+Mail sends/replies call AgentMail directly with the user's inbox-scoped key from `~/.autark/credentials.json`, then log an Autark `email` action containing `agentmail_thread_id` and `agentmail_inbox_id`.
+
 ## ENV
 
 - `AUTARK_API_URL` — override the default Worker URL (`https://autark-api.kushalsokke.workers.dev`)
+- `AGENTMAIL_API_URL` — override AgentMail API base
+- `AGENTMAIL_API_KEY`, `AGENTMAIL_EMAIL`, `AGENTMAIL_INBOX_ID` — override local mail credentials for debugging
 
 ## Architecture
 
 The CLI is a thin HTTP client over a Cloudflare Worker that holds the InstantDB admin token. Magic-link auth via InstantDB. Token saved to `~/.autark/credentials.json` after login.
 
-The web at autark.kushalsm.com is read-only. All writes (product, hypothesis, run, action) come through this CLI or future MCP server.
+The Worker uses the AgentMail org key only for provisioning and dashboard thread reads. Local mail send/reply uses the user's inbox-scoped key.

package/autark.mjs

@@ -1,13 +1,9 @@
 #!/usr/bin/env node
 // autark CLI — thin HTTP client over the autark-api Worker.
 //
-// Auth: magic-link flow saves a refresh_token to ~/.autark/credentials.json.
-// Every subsequent command sends it as `Authorization: Bearer <token>`.
-//
-// All business logic, schema knowledge, and InstantDB connectivity lives in
-// the Worker. The CLI is intentionally thin — it parses args, makes HTTP
-// calls, formats output. Replace this binary in any language tomorrow and
-// the system still works.
+// The runbook API is ID-first. slug/Hxx remains as a convenience alias.
+// Mail commands call AgentMail directly with the user's inbox-scoped key;
+// autark-api uses the org key only for provisioning and dashboard thread reads.
 
 import fs from 'node:fs'
 import os from 'node:os'
@@ -15,6 +11,7 @@ import path from 'node:path'
 import process from 'node:process'
 
 const API = process.env.AUTARK_API_URL || 'https://autark-api.kushalsokke.workers.dev'
+const AGENTMAIL_API = process.env.AGENTMAIL_API_URL || 'https://api.agentmail.to/v0'
 const CREDS_PATH = path.join(os.homedir(), '.autark', 'credentials.json')
 
 const args = process.argv.slice(2)
@@ -49,6 +46,7 @@ async function main() {
   }
   if (group === 'log' && command === 'action') return logAction(rest)
   if (group === 'context') return context([command, ...rest].filter(Boolean))
+  if (group === 'mail') return mail(command, rest)
 
   usage()
   process.exit(1)
@@ -71,6 +69,7 @@ async function loginVerify(rest) {
   const result = await api('POST', '/v1/auth/login/verify', { email, code }, { auth: false })
   if (!result.token) throw new Error('verify succeeded but no token returned')
   saveCredentials({
+    ...loadCredentials(),
     user_id: result.user.id,
     email:   result.user.email,
     token:   result.token,
@@ -116,7 +115,7 @@ async function productList() {
     return
   }
   for (const p of result.products) {
-    console.log(`${(p.slug || '').padEnd(20)} ${(p.visibility || '').padEnd(8)} ${p.name || ''}`)
+    console.log(`${(p.slug || '').padEnd(20)} ${(p.visibility || '').padEnd(8)} ${(p.id || '').padEnd(36)} ${p.name || ''}`)
   }
 }
 
@@ -124,45 +123,65 @@ async function productList() {
 
 async function hypothesisCreate(rest) {
   const opts = parseArgs(rest)
-  const product = required(opts.product, '--product')
-  const code    = required(opts.code, '--code')
-  const md      = readValue(required(opts.md, '--md'))
-  const title   = opts.title
-  const result = await api('POST', '/v1/hypotheses', {
-    product, code, md,
-    title:  title || undefined,
+  const md = readValue(required(opts.md, '--md'))
+  const body = {
+    md,
+    code:   opts.code || undefined,
+    title:  opts.title || undefined,
     status: opts.status || undefined,
-  })
+  }
+
+  let result
+  if (opts['product-id'] || opts.product_id) {
+    const productId = opts['product-id'] || opts.product_id
+    result = await api('POST', `/v1/products/${encodeURIComponent(productId)}/hypotheses`, body)
+  } else {
+    body.product = required(opts.product, '--product or --product-id')
+    result = await api('POST', '/v1/hypotheses', body)
+  }
   console.log(result.id)
 }
 
 async function hypothesisStatus(rest) {
   const opts = parseArgs(rest)
-  const ref  = required(opts._[0] || opts.hypothesis, 'hypothesis (e.g. chrome-relay/H01)')
   const status = required(opts.status, '--status')
-  const [productSlug, code] = splitHypothesisRef(ref)
-  const ctx = await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`)
-  const hypId = ctx.hypothesis?.id
-  if (!hypId) throw new Error(`hypothesis not found: ${ref}`)
-  const result = await api('PATCH', `/v1/hypotheses/${hypId}/status`, { status })
-  console.log(`${ref} → ${result.status}`)
+  let hypId = opts['hypothesis-id'] || opts.hypothesis_id || opts.id
+  let label = hypId
+
+  if (!hypId) {
+    const ref = required(opts._[0] || opts.hypothesis, 'hypothesis id or product/Hxx')
+    const [productSlug, code] = splitHypothesisRef(ref)
+    const ctx = await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`)
+    hypId = ctx.hypothesis?.id
+    label = ref
+  }
+  if (!hypId) throw new Error('hypothesis not found')
+
+  const result = await api('PATCH', `/v1/hypotheses/${encodeURIComponent(hypId)}/status`, { status })
+  console.log(`${label} → ${result.status}`)
 }
 
 // =============================================================== runs
 
 async function runStart(rest) {
   const opts = parseArgs(rest)
-  const ref  = required(opts.hypothesis || opts._[0], '--hypothesis (e.g. chrome-relay/H01)')
-  const [productSlug, code] = splitHypothesisRef(ref)
-  const result = await api('POST', '/v1/runs', { product: productSlug, hypothesis: code })
+  let result
+  const hypId = opts['hypothesis-id'] || opts.hypothesis_id
+  if (hypId) {
+    result = await api('POST', `/v1/hypotheses/${encodeURIComponent(hypId)}/runs`, {})
+  } else {
+    const ref = required(opts.hypothesis || opts._[0], '--hypothesis-id <id> or --hypothesis <slug/Hxx>')
+    const [productSlug, code] = splitHypothesisRef(ref)
+    result = await api('POST', '/v1/runs', { product: productSlug, hypothesis: code })
+  }
   console.log(result.id)
 }
 
 async function runFinish(rest) {
   const opts = parseArgs(rest)
-  const id   = required(opts.run, '--run')
+  const id = required(opts['run-id'] || opts.run_id || opts.run, '--run-id')
   const narrative = readValue(required(opts.narrative, '--narrative'))
-  const result = await api('PATCH', `/v1/runs/${id}/finish`, { narrative_md: narrative })
+  const result = await api('PATCH', `/v1/runs/${encodeURIComponent(id)}/finish`, { narrative_md: narrative })
   console.log(`${result.id}  finished_at=${result.finished_at}`)
 }
 
@@ -170,52 +189,286 @@ async function runFinish(rest) {
 
 async function logAction(rest) {
   const opts = parseArgs(rest)
-  const run = required(opts.run, '--run')
+  const run = required(opts['run-id'] || opts.run_id || opts.run, '--run-id')
   const channel = required(opts.channel, '--channel')
   const title   = required(opts.title, '--title')
-  const result = await api('POST', '/v1/actions', {
-    run,
+  const result = await api('POST', `/v1/runs/${encodeURIComponent(run)}/actions`, {
     channel,
     title,
-    url:                 opts.url || undefined,
-    agentmail_thread_id: opts['agentmail-thread-id'] || opts['thread-id'] || opts.thread_id || undefined,
-    recipient:           opts.recipient || undefined,
-    metadata:            opts.metadata ? JSON.parse(readValue(opts.metadata)) : undefined,
-    occurred_at:         opts['occurred-at'] || opts.occurred_at || undefined,
+    url:                  opts.url || undefined,
+    agentmail_thread_id:  opts['agentmail-thread-id'] || opts['thread-id'] || opts.thread_id || undefined,
+    agentmail_inbox_id:   opts['agentmail-inbox-id'] || opts.inbox_id || opts.agentmail_inbox_id || undefined,
+    recipient:            opts.recipient || undefined,
+    metadata:             opts.metadata ? JSON.parse(readValue(opts.metadata)) : undefined,
+    occurred_at:          opts['occurred-at'] || opts.occurred_at || undefined,
   })
   console.log(result.id)
 }
 
+// ============================================================ mail
+
+async function mail(command, rest) {
+  if (!command || command === '--help' || command === 'help') return mailUsage()
+  if (command === 'setup')     return mailSetup(rest)
+  if (command === 'send')      return mailSend(rest)
+  if (command === 'reply')     return mailReply(rest, 'reply')
+  if (command === 'reply-all') return mailReply(rest, 'reply-all')
+  if (command === 'forward')   return mailForward(rest)
+  if (command === 'threads')   return mailThreads(rest)
+  if (command === 'thread')    return mailThread(rest)
+  if (command === 'messages')  return mailMessages(rest)
+  if (command === 'message')   return mailMessage(rest)
+  if (command === 'raw')       return mailRaw(rest)
+  if (command === 'attachment') return mailAttachment(rest)
+  if (command === 'request')   return mailRequest(rest)
+  mailUsage()
+  process.exit(1)
+}
+
+async function mailSetup(rest) {
+  const opts = parseArgs(rest)
+  const existing = loadCredentials() || {}
+  if (existing.agentmail_token && existing.agentmail_email && !opts.force) {
+    console.log(existing.agentmail_email)
+    return
+  }
+  const prefix = required(opts.prefix || defaultInboxPrefix(existing.email), '--prefix')
+  const result = await api('POST', '/v1/onboard/agentmail', {
+    prefix,
+    display_name: opts['display-name'] || opts.display_name || existing.email || prefix,
+    purpose: opts.purpose || 'runner',
+  })
+  saveCredentials({
+    ...existing,
+    agentmail_email:      result.agentmail_email || result.email,
+    agentmail_inbox_id:   result.agentmail_inbox_id || result.inbox_id || result.email,
+    agentmail_api_key_id: result.agentmail_api_key_id || result.api_key_id,
+    agentmail_token:      result.agentmail_token,
+    agentmail_saved_at:   new Date().toISOString(),
+  })
+  console.log(result.agentmail_email || result.email)
+}
+
+async function mailSend(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const to = listOpt(opts.to, '--to')
+  const subject = opts.subject || ''
+  const body = mailBody(opts, { to, subject })
+  const result = await agentmailRequest('POST', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/send`, body)
+  const action = await maybeLogMailAction(opts, {
+    kind: 'send',
+    defaultTitle: opts.title || `Email: ${subject || to.join(', ')}`,
+    recipient: to.join(','),
+    subject,
+    response: result,
+  })
+  printJson({ ...result, autark_action_id: action?.id })
+}
+
+async function mailReply(rest, mode) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], '--message-id')
+  const body = mailBody(opts)
+  const endpoint = mode === 'reply-all' ? 'reply-all' : 'reply'
+  const result = await agentmailRequest('POST', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/${endpoint}`, body)
+  const action = await maybeLogMailAction(opts, {
+    kind: mode,
+    defaultTitle: opts.title || `${mode === 'reply-all' ? 'Reply-all' : 'Reply'}: ${messageId}`,
+    recipient: listOpt(opts.to).join(','),
+    response: result,
+    metadata: { message_id: messageId },
+  })
+  printJson({ ...result, autark_action_id: action?.id })
+}
+
+async function mailForward(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], '--message-id')
+  const to = listOpt(opts.to, '--to')
+  const body = mailBody(opts, { to, subject: opts.subject || '' })
+  const result = await agentmailRequest('POST', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/forward`, body)
+  const action = await maybeLogMailAction(opts, {
+    kind: 'forward',
+    defaultTitle: opts.title || `Forward: ${opts.subject || messageId}`,
+    recipient: to.join(','),
+    response: result,
+    metadata: { message_id: messageId },
+  })
+  printJson({ ...result, autark_action_id: action?.id })
+}
+
+async function mailThreads(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const qs = queryString({ limit: opts.limit, page_token: opts['page-token'] || opts.page_token })
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/threads${qs}`))
+}
+
+async function mailThread(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const threadId = required(opts['thread-id'] || opts.thread_id || opts._[0], 'thread_id')
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/threads/${encodeURIComponent(threadId)}`))
+}
+
+async function mailMessages(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const qs = queryString({ limit: opts.limit, page_token: opts['page-token'] || opts.page_token })
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages${qs}`))
+}
+
+async function mailMessage(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], 'message_id')
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}`))
+}
+
+async function mailRaw(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], 'message_id')
+  const raw = await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/raw`, undefined, { parseJson: false })
+  process.stdout.write(raw)
+}
+
+async function mailAttachment(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id, '--message-id')
+  const attachmentId = required(opts['attachment-id'] || opts.attachment_id, '--attachment-id')
+  const body = await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`, undefined, { parseJson: false })
+  if (opts.out) fs.writeFileSync(opts.out, body)
+  else process.stdout.write(body)
+}
+
+async function mailRequest(rest) {
+  const opts = parseArgs(rest)
+  const method = (opts.method || opts._[0] || 'GET').toUpperCase()
+  const requestPath = required(opts.path || opts._[1], '--path')
+  const body = opts.body ? JSON.parse(readValue(opts.body)) : undefined
+  const parseJson = opts.raw ? false : true
+  const result = await agentmailRequest(method, requestPath.startsWith('/') ? requestPath : `/${requestPath}`, body, { parseJson })
+  if (parseJson) printJson(result)
+  else process.stdout.write(result)
+}
+
+function mailBody(opts, base = {}) {
+  const body = { ...base }
+  if (opts.text !== undefined) body.text = readValue(opts.text)
+  if (opts.html !== undefined) body.html = readValue(opts.html)
+  if (opts.subject !== undefined) body.subject = opts.subject
+  for (const key of ['cc', 'bcc', 'reply-to', 'label', 'attachment']) {
+    const snake = key.replaceAll('-', '_')
+    const value = opts[key] ?? opts[snake]
+    if (value !== undefined) body[snake] = listOpt(value)
+  }
+  if (opts.headers !== undefined) body.headers = JSON.parse(readValue(opts.headers))
+  return body
+}
+
+async function maybeLogMailAction(opts, { kind, defaultTitle, recipient, subject, response, metadata = {} }) {
+  const runId = opts['run-id'] || opts.run_id || opts.run
+  if (!runId) return null
+  const creds = requireAgentmailCredentials()
+  const threadId = response?.thread_id
+  if (!threadId) throw new Error('AgentMail response missing thread_id; refusing to log email action')
+  return api('POST', `/v1/runs/${encodeURIComponent(runId)}/actions`, {
+    channel: 'email',
+    title: opts.title || defaultTitle,
+    recipient: recipient || undefined,
+    agentmail_thread_id: threadId,
+    agentmail_inbox_id: creds.inboxId,
+    metadata: compact({
+      kind,
+      subject,
+      message_id: response?.message_id,
+      ...metadata,
+    }),
+  })
+}
+
+async function agentmailRequest(method, pathStr, body, { parseJson = true } = {}) {
+  const creds = requireAgentmailCredentials()
+  const res = await fetch(AGENTMAIL_API + pathStr, {
+    method,
+    headers: {
+      authorization: `Bearer ${creds.token}`,
+      'content-type': 'application/json',
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  })
+  const text = await res.text()
+  let data = text
+  if (parseJson) {
+    try { data = text ? JSON.parse(text) : null } catch { data = { raw: text } }
+  }
+  if (!res.ok) {
+    const msg = parseJson ? (data?.error || data?.message || JSON.stringify(data)) : text
+    throw new Error(`AgentMail ${res.status}: ${msg}`)
+  }
+  return data
+}
+
+function requireAgentmailCredentials() {
+  const creds = loadCredentials()
+  const token = process.env.AGENTMAIL_API_KEY || creds?.agentmail_token
+  const email = process.env.AGENTMAIL_EMAIL || creds?.agentmail_email
+  const inboxId = process.env.AGENTMAIL_INBOX_ID || creds?.agentmail_inbox_id || email
+  if (!token) throw new Error('missing agentmail_token. run: autark mail setup --prefix <name>')
+  if (!inboxId) throw new Error('missing agentmail_inbox_id. run: autark mail setup --prefix <name>')
+  return { token, email, inboxId }
+}
+
 // ============================================================ context
 
 async function context(rest) {
   const opts = parseArgs(rest)
-  const ref = required(opts._[0] || opts.hypothesis, 'product or hypothesis (e.g. chrome-relay or chrome-relay/H01)')
+
+  if (opts['product-id'] || opts.product_id) {
+    const productId = opts['product-id'] || opts.product_id
+    return printProductContext(await api('GET', `/v1/products/${encodeURIComponent(productId)}/context`))
+  }
+
+  if (opts['hypothesis-id'] || opts.hypothesis_id) {
+    const hypId = opts['hypothesis-id'] || opts.hypothesis_id
+    return printHypothesisContext(await api('GET', `/v1/hypotheses/${encodeURIComponent(hypId)}/context`))
+  }
+
+  const ref = required(opts._[0] || opts.hypothesis, 'product slug, product/Hxx, --product-id, or --hypothesis-id')
   const parts = ref.split('/')
   const productSlug = parts[0]
   const code = parts[1]
 
-  if (!code) {
-    // product-level: brief + every hypothesis with status + counts
-    const r = await api('GET', `/v1/context/${encodeURIComponent(productSlug)}`)
-    console.log(`# ${r.product.slug} — ${r.product.name}`)
-    if (r.product.tagline) console.log(`> ${r.product.tagline}`)
-    if (r.product.url)     console.log(`> ${r.product.url}`)
-    console.log(`\n## Brief\n`)
-    console.log(r.product.brief?.trim() || '(no brief set — owner can add one at https://autark.kushalsm.com)')
-    console.log(`\n## Hypotheses (${r.hypotheses.length})\n`)
-    if (!r.hypotheses.length) {
-      console.log('(none yet — start with H01)')
-    } else {
-      for (const h of r.hypotheses) {
-        console.log(`- [${h.status}] ${h.code} — ${h.title}  (runs: ${h.run_count})`)
-      }
+  if (!code) return printProductContext(await api('GET', `/v1/context/${encodeURIComponent(productSlug)}`))
+  return printHypothesisContext(await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`))
+}
+
+function printProductContext(r) {
+  console.log(`# ${r.product.slug} — ${r.product.name}`)
+  console.log(`id: ${r.product.id}`)
+  if (r.product.tagline) console.log(`> ${r.product.tagline}`)
+  if (r.product.url)     console.log(`> ${r.product.url}`)
+  console.log(`\n## Brief\n`)
+  console.log(r.product.brief?.trim() || '(no brief set — owner can add one at https://autark.kushalsm.com)')
+  console.log(`\n## Hypotheses (${r.hypotheses.length})\n`)
+  if (!r.hypotheses.length) {
+    console.log('(none yet — create one with: autark hypothesis create --product-id <product_id> --md @hyp.md)')
+  } else {
+    for (const h of r.hypotheses) {
+      console.log(`- [${h.status}] ${h.code}  id=${h.id}  — ${h.title}  (runs: ${h.run_count})`)
     }
-    return
   }
+}
 
-  const result = await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`)
+function printHypothesisContext(result) {
   console.log(`# ${result.product.slug}/${result.hypothesis.code} — ${result.hypothesis.title}\n`)
+  console.log(`product_id: ${result.product.id}`)
+  console.log(`hypothesis_id: ${result.hypothesis.id}`)
   console.log(`Status: ${result.hypothesis.status}\n`)
   console.log(result.hypothesis.hypothesis_md)
   for (const run of result.runs) {
@@ -228,9 +481,7 @@ async function context(rest) {
         console.log(`  [${a.channel}] ${a.title}${pointer ? `  →  ${pointer}` : ''}`)
       }
     }
-    if (run.narrative_md) {
-      console.log(`\n${run.narrative_md}`)
-    }
+    if (run.narrative_md) console.log(`\n${run.narrative_md}`)
   }
 }
 
@@ -265,14 +516,10 @@ function saveCredentials(creds) {
 
 function loadCredentials() {
   if (!fs.existsSync(CREDS_PATH)) return null
-  try {
-    return JSON.parse(fs.readFileSync(CREDS_PATH, 'utf8'))
-  } catch {
-    return null
-  }
+  try { return JSON.parse(fs.readFileSync(CREDS_PATH, 'utf8')) } catch { return null }
 }
 
-// ============================================================ arg parsing
+// ============================================================ utilities
 
 function parseArgs(list) {
   const opts = { _: [] }
@@ -284,12 +531,11 @@ function parseArgs(list) {
     }
     const key = arg.slice(2)
     const next = list[i + 1]
-    if (!next || next.startsWith('--')) {
-      opts[key] = true
-    } else {
-      opts[key] = next
-      i++
-    }
+    const value = (!next || next.startsWith('--')) ? true : next
+    if (value !== true) i++
+    if (opts[key] === undefined) opts[key] = value
+    else if (Array.isArray(opts[key])) opts[key].push(value)
+    else opts[key] = [opts[key], value]
   }
   return opts
 }
@@ -302,12 +548,43 @@ function required(value, label) {
 }
 
 function readValue(value) {
-  if (typeof value === 'string' && value.startsWith('@')) {
-    return fs.readFileSync(value.slice(1), 'utf8')
-  }
+  if (typeof value === 'string' && value.startsWith('@')) return fs.readFileSync(value.slice(1), 'utf8')
   return String(value)
 }
 
+function listOpt(value, label) {
+  if (value === undefined || value === null || value === '') {
+    if (label) throw new Error(`${label} is required`)
+    return []
+  }
+  const values = Array.isArray(value) ? value : [value]
+  return values.flatMap(v => String(v).split(',')).map(v => v.trim()).filter(Boolean)
+}
+
+function queryString(params) {
+  const q = new URLSearchParams()
+  for (const [k, v] of Object.entries(params)) if (v !== undefined && v !== null && v !== '') q.set(k, v)
+  const s = q.toString()
+  return s ? `?${s}` : ''
+}
+
+function defaultInboxPrefix(email) {
+  if (!email) return ''
+  return String(email).split('@')[0].toLowerCase().replace(/[^a-z0-9._-]/g, '').replace(/^[._-]+/, '').slice(0, 30)
+}
+
+function compact(obj) {
+  const out = {}
+  for (const [k, v] of Object.entries(obj || {})) {
+    if (v !== undefined && v !== null && v !== '' && !(Array.isArray(v) && !v.length)) out[k] = v
+  }
+  return out
+}
+
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2))
+}
+
 function splitHypothesisRef(ref) {
   const m = String(ref).match(/^([\w.-]+)\/(H\d{2})$/)
   if (!m) throw new Error(`expected product/Hxx, got ${ref}`)
@@ -317,8 +594,26 @@ function splitHypothesisRef(ref) {
 // ============================================================ usage
 
 function loginUsage() {
-  console.log(`autark login send <email>
-autark login verify <email> --code <6-digit-code>`)
+  console.log(`autark login send <email>\nautark login verify <email> --code <6-digit-code>`)
+}
+
+function mailUsage() {
+  console.log(`autark mail
+
+  setup       --prefix <name> [--force]
+  send        --to <email[,email]> --subject <s> --text @body.txt [--run-id <id>]
+  reply       --message-id <id> --text @reply.txt [--run-id <id>]
+  reply-all   --message-id <id> --text @reply.txt [--run-id <id>]
+  forward     --message-id <id> --to <email> [--text @body.txt] [--run-id <id>]
+  threads     [--limit N]
+  thread      <thread_id>
+  messages    [--limit N]
+  message     <message_id>
+  raw         <message_id>
+  attachment  --message-id <id> --attachment-id <id> [--out file]
+  request     <METHOD> <path> [--body @json] [--raw]
+
+Mail uses the inbox-scoped token in ~/.autark/credentials.json.`)
 }
 
 function usage() {
@@ -330,17 +625,25 @@ function usage() {
   autark me                                                show signed-in user
 
   autark product upsert --slug <slug> --name <name> [--url <url>] [--tagline <text>] [--brief @./brief.md] [--visibility private|public]
-  autark product list
+  autark product list                                      prints slug, visibility, id, name
 
-  autark hypothesis create --product <slug> --code H01 --md @./hypothesis.md [--title <t>]
-  autark hypothesis status <slug>/<H01> --status active|inactive|dead
+  autark hypothesis create --product-id <id> --md @./hyp.md [--code H01] [--title <t>]
+  autark hypothesis create --product <slug> --md @./hyp.md [--code H01] [--title <t>]   # alias
+  autark hypothesis status --hypothesis-id <id> --status active|inactive|dead
+  autark hypothesis status <slug>/<H01> --status active|inactive|dead                  # alias
 
-  autark run start --hypothesis <slug>/<H01>
-  autark run finish --run <id> --narrative @./run.md
+  autark run start --hypothesis-id <id>
+  autark run start --hypothesis <slug>/<H01>                                           # alias
+  autark run finish --run-id <id> --narrative @./run.md
 
-  autark log action --run <id> --channel <c> --title <t> [--url <u>]
-                    [--agentmail-thread-id <uuid>] [--recipient <email>]
+  autark log action --run-id <id> --channel <c> --title <t> [--url <u>]
+                    [--agentmail-thread-id <uuid>] [--agentmail-inbox-id <inbox>] [--recipient <email>]
                     [--metadata @./meta.json]
 
+  autark mail setup/send/reply/thread/messages/...       AgentMail via autark credentials
+
+  autark context --product-id <id>
+  autark context --hypothesis-id <id>
+  autark context <slug>
   autark context <slug>/<H01>`)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autark-cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "CLI for autark — hypothesis-driven product runbooks. Track products, hypotheses, runs, and actions from the terminal.",
   "type": "module",
   "license": "MIT",