@astrale-os/cli 0.8.1-alpha.4 → 0.8.1-alpha.6

package/src/commands/identity/import.ts

@@ -8,6 +8,7 @@ import {
   isEncryptedIdentityExport,
 } from '../../identity/index'
 import { fatal, log } from '../../lib/log'
+import { isMachine, output, RAW_OUTPUT_OPTIONS, type RawOutputOpts } from '../../lib/output'
 import { readPassphrase } from '../../lib/prompt'
 
 export default {
@@ -27,8 +28,12 @@ export default {
       flags: '--replace',
       description: 'Replace an existing key-backed identity with the imported keypair',
     },
+    ...RAW_OUTPUT_OPTIONS,
   ],
-  action: async (path: string, opts: { name?: string; issuer?: string; replace?: boolean }) => {
+  action: async (
+    path: string,
+    opts: { name?: string; issuer?: string; replace?: boolean } & RawOutputOpts,
+  ) => {
     try {
       const raw = await readFile(path, 'utf-8')
       const passphrase = isEncryptedIdentityExport(raw)
@@ -42,11 +47,15 @@ export default {
         replace: opts.replace,
       })
 
+      if (isMachine(opts)) {
+        output({ name, ...identity }, opts)
+        return
+      }
       log.success(
         `Imported identity "${name}" (subject=${identity.subject}, kid=${identity.kid ?? '?'})`,
       )
     } catch (e) {
-      fatal(e)
+      fatal(e, opts)
     }
   },
 } satisfies CommandDefinition

package/src/commands/identity/sync.ts

@@ -2,6 +2,7 @@ import type { CommandDefinition } from '../../program/index'
 
 import { getIdentity, setIdentityMode } from '../../identity/index'
 import { fatal, fatalNotImplemented, log } from '../../lib/log'
+import { isMachine, output, RAW_OUTPUT_OPTIONS, type RawOutputOpts } from '../../lib/output'
 
 export default {
   name: 'sync',
@@ -12,8 +13,9 @@ export default {
       flags: '--force',
       description: 'Tag as remote in the local registry even without cloud login',
     },
+    ...RAW_OUTPUT_OPTIONS,
   ],
-  action: async (name: string, opts: { force?: boolean }) => {
+  action: async (name: string, opts: { force?: boolean } & RawOutputOpts) => {
     try {
       const identity = await getIdentity(name)
       if (!opts.force) {
@@ -23,10 +25,14 @@ export default {
         )
       }
       await setIdentityMode(name, 'remote')
+      if (isMachine(opts)) {
+        output({ name, mode: 'remote', subject: identity.subject }, opts)
+        return
+      }
       log.warn(`Tagged "${name}" as remote locally (cloud sync stubbed in v1)`)
       log.dim(`  subject=${identity.subject}`)
     } catch (e) {
-      fatal(e)
+      fatal(e, opts)
     }
   },
 } satisfies CommandDefinition

package/src/commands/identity/unsync.ts

@@ -2,23 +2,33 @@ import type { CommandDefinition } from '../../program/index'
 
 import { getIdentity, setIdentityMode } from '../../identity/index'
 import { fatal, log } from '../../lib/log'
+import { isMachine, output, RAW_OUTPUT_OPTIONS, type RawOutputOpts } from '../../lib/output'
 
 /** Metadata-only flip remote → local until cloud sync ships (§2.7). */
 export default {
   name: 'unsync',
   description: 'Migrate an identity remote → local',
   arguments: [{ name: 'name', description: 'Identity name', required: true }],
-  action: async (name: string) => {
+  options: [...RAW_OUTPUT_OPTIONS],
+  action: async (name: string, opts: RawOutputOpts) => {
     try {
       const identity = await getIdentity(name)
       if (identity.mode !== 'remote') {
+        if (isMachine(opts)) {
+          output({ name, mode: identity.mode ?? 'local', unchanged: true }, opts)
+          return
+        }
         log.warn(`Identity "${name}" is already ${identity.mode ?? 'local'}`)
         return
       }
       await setIdentityMode(name, 'local')
+      if (isMachine(opts)) {
+        output({ name, mode: 'local' }, opts)
+        return
+      }
       log.success(`Identity "${name}" → local`)
     } catch (e) {
-      fatal(e)
+      fatal(e, opts)
     }
   },
 } satisfies CommandDefinition

package/src/commands/identity/use.ts

@@ -2,17 +2,23 @@ import type { CommandDefinition } from '../../program/index'
 
 import { setDefault } from '../../identity/index'
 import { fatal, log } from '../../lib/log'
+import { isMachine, output, RAW_OUTPUT_OPTIONS, type RawOutputOpts } from '../../lib/output'
 
 export default {
   name: 'use',
   description: 'Set the active CLI identity',
   arguments: [{ name: 'name', description: 'Identity name', required: true }],
-  action: async (name: string) => {
+  options: [...RAW_OUTPUT_OPTIONS],
+  action: async (name: string, opts: RawOutputOpts) => {
     try {
       await setDefault(name)
+      if (isMachine(opts)) {
+        output({ default: name }, opts)
+        return
+      }
       log.success(`Active identity set to "${name}"`)
     } catch (e) {
-      fatal(e)
+      fatal(e, opts)
     }
   },
 } satisfies CommandDefinition

package/src/commands/identity/whoami.ts

@@ -28,7 +28,7 @@ export default {
       }
       console.log(`${chalk.bold(result.name)} (subject: ${result.subject})`)
     } catch (e) {
-      fatal(e)
+      fatal(e, opts)
     }
   },
 } satisfies CommandDefinition

package/src/commands/introspect.ts

@@ -0,0 +1,117 @@
+import { Path } from '@astrale-os/sdk/graph/path'
+
+import type { KernelCommandOpts } from '../connection'
+import type { CommandDefinition } from '../program/index'
+
+import { runKernelCommand } from '../connection'
+import { AstraleError } from '../errors'
+import { failClosed } from '../lib/log'
+import { output } from '../lib/output'
+import { describeCallableFromSchema, missingCallableDescription } from './call-describe'
+
+type IntrospectOpts = KernelCommandOpts & { bundle?: boolean }
+
+export async function introspectCommand(target: string, opts: IntrospectOpts): Promise<void> {
+  let origin: string
+  let path: Path
+  try {
+    ;({ origin, path } = parseIntrospectTarget(target))
+  } catch (error) {
+    failClosed(error, opts)
+  }
+  const wantsCallable = isCallablePath(path)
+
+  await runKernelCommand({
+    opts,
+    label: `Introspect ${origin}`,
+    fn: async ({ session }) => {
+      const includeBundle = wantsCallable || opts.bundle === true
+      const result = await session.schema.introspect({
+        from: { kind: 'installation', origin },
+        select: {
+          state: true,
+          target: true,
+          source: true,
+          readiness: true,
+          capabilities: true,
+          ...(includeBundle ? { bundle: true as const } : {}),
+        },
+      })
+      if (result === null) {
+        throw new AstraleError(
+          'DOMAIN_NOT_INSTALLED',
+          `Domain ${origin} is not installed on this Kernel.`,
+        )
+      }
+      if (wantsCallable) {
+        const described = describeCallableFromSchema(path, bundleRoot(result.bundle))
+        if (described === undefined) throw missingCallableDescription(path.raw)
+        return described
+      }
+      return result
+    },
+    format: (value, format) => output(value, format),
+  })
+}
+
+export function parseIntrospectTarget(target: string): { origin: string; path: Path } {
+  if (target.startsWith('@')) {
+    throw new AstraleError(
+      'NOT_A_DOMAIN',
+      'introspect requires a Domain origin or Path, not an @id.',
+      'Example: astrale introspect host.astrale.ai  or  /:host.astrale.ai:class.Manager:createInstance',
+    )
+  }
+  const raw = target.startsWith('/') ? target : `/:${target}`
+  let path: Path
+  try {
+    path = Path.parse(raw)
+  } catch (error) {
+    throw new AstraleError(
+      'PATH_INVALID',
+      error instanceof Error ? error.message : 'Invalid introspect target',
+    )
+  }
+  if (path.ast.anchor.kind !== 'domain') {
+    throw new AstraleError('NOT_A_DOMAIN', 'introspect requires a Domain-rooted Path or origin.')
+  }
+  return { origin: path.ast.anchor.origin, path }
+}
+
+function isCallablePath(path: Path): boolean {
+  const last = path.ast.steps.at(-1)
+  if (last === undefined) return false
+  if (last.kind === 'method') return true
+  return last.kind === 'projection' && last.projection.kind === 'function'
+}
+
+function bundleRoot(bundle: unknown): unknown {
+  if (bundle !== null && typeof bundle === 'object' && 'root' in bundle) {
+    return (bundle as { root: unknown }).root
+  }
+  return bundle
+}
+
+export default {
+  name: 'introspect',
+  description: 'Read installed Domain schema from the Kernel Schema syscall',
+  afterHelpText: `
+Behavior:
+  Calls the public Kernel introspect syscall for one installed Domain.
+  A bare origin (host.astrale.ai or /:host.astrale.ai) prints installation
+  state, target, source, readiness, and capabilities. --bundle includes the
+  schema bundle. A method or Function Path projects that callable's
+  input/output from the installed bundle.
+
+Examples:
+  $ astrale introspect host.astrale.ai
+  $ astrale introspect /:host.astrale.ai --bundle
+  $ astrale introspect /:host.astrale.ai:class.Manager:createInstance
+  $ astrale introspect /:kernel.astrale.ai:function.journal
+`,
+  arguments: [{ name: 'target', description: 'Domain origin or canonical Path' }],
+  options: [{ flags: '--bundle', description: 'Include the installed schema bundle' }],
+  action: async (target, opts) => {
+    await introspectCommand(target as string, opts as IntrospectOpts)
+  },
+} satisfies CommandDefinition

package/src/commands/logs.ts

@@ -6,7 +6,13 @@ import type { ConnectionContext, KernelCommandOpts } from '../connection'
 import type { Column, ListProjection } from '../lib/output'
 import type { CommandDefinition } from '../program/index'
 
-import { createPathCall, runKernelCommand, withClientSession } from '../connection'
+import {
+  createPathCall,
+  expandSelfInPath,
+  runKernelCommand,
+  withClientSession,
+} from '../connection'
+import { failClosed } from '../lib/log'
 import { isMachine, output, presentList } from '../lib/output'
 
 const JOURNAL_PATH = Path.project(syscalls.journal.ref).raw
@@ -50,10 +56,18 @@ export interface JournalInput {
   readonly limit: number
 }
 
+const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+const CURSOR_TOKEN = /^[A-Za-z0-9._:+=/-]{8,}$/
+
 /** Map flags to the exact public journal syscall input without legacy glob/sequence lowering. */
 export function buildJournalInput(opts: LogsOpts): JournalInput {
   const exact = nonEmpty(opts.topic)
   const prefix = nonEmpty(opts.topicPrefix)
+  const since = timestampFlag('--since', opts.since)
+  const until = timestampFlag('--until', opts.until)
+  if (since !== undefined && until !== undefined && Date.parse(since) > Date.parse(until)) {
+    throw new TypeError('--since must be earlier than or equal to --until')
+  }
   return {
     ...(exact === undefined && prefix === undefined
       ? {}
@@ -64,13 +78,30 @@ export function buildJournalInput(opts: LogsOpts): JournalInput {
           },
         }),
     ...(nonEmpty(opts.principal) === undefined ? {} : { principal: opts.principal }),
-    ...(nonEmpty(opts.since) === undefined ? {} : { since: opts.since }),
-    ...(nonEmpty(opts.until) === undefined ? {} : { until: opts.until }),
-    ...(nonEmpty(opts.cursor) === undefined ? {} : { cursor: opts.cursor }),
+    ...(since === undefined ? {} : { since }),
+    ...(until === undefined ? {} : { until }),
+    ...(opts.cursor === undefined ? {} : { cursor: cursorFlag(opts.cursor) }),
     limit: opts.limit === undefined ? DEFAULT_LIMIT : positiveInteger('--limit', opts.limit),
   }
 }
 
+function timestampFlag(name: string, raw: string | undefined): string | undefined {
+  const value = nonEmpty(raw)
+  if (value === undefined) return undefined
+  if (!ISO_TIMESTAMP.test(value) || Number.isNaN(Date.parse(value))) {
+    throw new TypeError(`${name} must be an ISO-8601 timestamp (e.g. 2026-08-19T16:51:10.049Z)`)
+  }
+  return value
+}
+
+function cursorFlag(raw: string): string {
+  const value = raw.trim()
+  if (!CURSOR_TOKEN.test(value)) {
+    throw new TypeError('--cursor must be an opaque journal resume token (at least 8 characters)')
+  }
+  return value
+}
+
 /** Validate the record fields the CLI presentation consumes and retain the opaque cursor. */
 export function acceptJournalPage(input: unknown): JournalPage {
   if (!isRecord(input) || !Array.isArray(input.records)) {
@@ -196,6 +227,14 @@ function positiveInteger(flag: string, raw: string): number {
   return value
 }
 
+async function prepareLogsOpts(opts: LogsOpts): Promise<LogsOpts> {
+  buildJournalInput(opts)
+  const principal = nonEmpty(opts.principal)
+  if (principal !== '@self') return opts
+  const { path } = await expandSelfInPath('@self', opts)
+  return { ...opts, principal: path.startsWith('@') ? path.slice(1) : path }
+}
+
 function nonEmpty(input: string | undefined): string | undefined {
   const value = input?.trim()
   return value ? value : undefined
@@ -234,7 +273,12 @@ Examples:
     { flags: '--follow', description: 'Poll using returned cursors until interrupted' },
   ],
   action: async (opts: LogsOpts) => {
-    if (opts.follow) await follow(opts)
-    else await runOnce(opts)
+    try {
+      const prepared = await prepareLogsOpts(opts)
+      if (prepared.follow) await follow(prepared)
+      else await runOnce(prepared)
+    } catch (error) {
+      failClosed(error, opts)
+    }
   },
 } satisfies CommandDefinition

package/src/commands/mutate.ts

@@ -8,7 +8,7 @@ import type { CommandDefinition } from '../program/index'
 
 import { runKernelCommand } from '../connection'
 import { prepareMutation } from '../graph/index'
-import { log } from '../lib/log'
+import { failClosed } from '../lib/log'
 import { output } from '../lib/output'
 import { renderTable } from '../lib/table'
 
@@ -23,8 +23,7 @@ export async function mutateCommand(opts: MutateOpts): Promise<void> {
   try {
     mutation = prepareMutation(await readDocument(opts))
   } catch (error) {
-    log.error(error instanceof Error ? error.message : 'Invalid Mutation V3 document')
-    process.exit(1)
+    failClosed(error, opts)
   }
 
   if (opts.dry) {

package/src/commands/query.ts

@@ -7,7 +7,7 @@ import type { CommandDefinition } from '../program/index'
 
 import { expandSelfInPath, runKernelCommand, withSelfHint } from '../connection'
 import { prepareQuery, type QueryCommandInput } from '../graph/index'
-import { log } from '../lib/log'
+import { failClosed } from '../lib/log'
 import { isMachine, output } from '../lib/output'
 
 type QueryOpts = KernelCommandOpts & {
@@ -48,16 +48,14 @@ export async function queryCommand(sources: string[], opts: QueryOpts): Promise<
       }
     }
   } catch (error) {
-    log.error(error instanceof Error ? error.message : 'Invalid query')
-    process.exit(1)
+    failClosed(error, opts)
   }
 
   let prepared
   try {
     prepared = prepareQuery(input)
   } catch (error) {
-    log.error(error instanceof Error ? error.message : 'Invalid Query V6 document')
-    process.exit(1)
+    failClosed(error, opts)
   }
 
   await runKernelCommand({

package/src/commands/token.ts

@@ -4,7 +4,10 @@ import type { KernelCommandOpts } from '../connection'
 import type { CommandDefinition } from '../program/index'
 
 import { runKernelCommand } from '../connection'
-import { log } from '../lib/log'
+import { AstraleError } from '../errors'
+import { decodeJwtExpiration } from '../lib/local-status'
+import { failClosed, log } from '../lib/log'
+import { output } from '../lib/output'
 
 /**
  * `astrale token` — mint a fresh delegation token for the active instance
@@ -20,6 +23,7 @@ export type TokenOpts = KernelCommandOpts & {
 
 export async function tokenCommand(opts: TokenOpts): Promise<void> {
   const commandOpts: TokenOpts = opts.for && !opts.as ? { ...opts, as: opts.for } : opts
+  const ttl = parseTtl(commandOpts.ttl)
   await runKernelCommand<string>({
     opts: commandOpts,
     label: 'Minting delegation token',
@@ -28,8 +32,6 @@ export async function tokenCommand(opts: TokenOpts): Promise<void> {
         commandOpts.audience === undefined
           ? ctx.target.kernelIssuer
           : issuer.accept(commandOpts.audience)
-      const parsedTtl = Number(commandOpts.ttl)
-      const ttl = Number.isFinite(parsedTtl) && parsedTtl > 0 ? parsedTtl : 3600
       const self = await ctx.auth.whoami()
       return ctx.auth.delegate(self.id, {
         audience,
@@ -37,17 +39,37 @@ export async function tokenCommand(opts: TokenOpts): Promise<void> {
         attenuation: { kind: 'identity', self: true },
       })
     },
-    format: (token, fmtOpts, isRaw) => {
-      if (isRaw) {
-        process.stdout.write(token + '\n')
+    format: (token, fmtOpts) => {
+      if (fmtOpts.json || fmtOpts.format !== undefined) {
+        output({ token, expiresAt: decodeJwtExpiration(token)?.expiresAt ?? null }, fmtOpts)
         return
       }
-      log.dim('  (delegation token — ES256, self-identity)')
+      if (!fmtOpts.raw && (process.stdout.isTTY ?? false)) {
+        log.dim('  (delegation token — ES256, self-identity)')
+      }
       process.stdout.write(`${token}\n`)
     },
   })
 }
 
+export function parseTtl(raw: string | undefined): number {
+  if (raw === undefined) return 3600
+  if (!/^\d+$/.test(raw)) {
+    throw new AstraleError(
+      'INVALID_FLAG',
+      `Invalid --ttl value "${raw}" — expected a positive integer (seconds)`,
+    )
+  }
+  const value = Number.parseInt(raw, 10)
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new AstraleError(
+      'INVALID_FLAG',
+      `Invalid --ttl value "${raw}" — must be a positive integer`,
+    )
+  }
+  return value
+}
+
 export default {
   name: 'token',
   description: 'Mint a fresh delegation token for the active instance + identity',
@@ -63,6 +85,7 @@ Behavior:
 
 Examples:
   $ export TOKEN=$(astrale token --audience shell.astrale.ai --raw)
+  $ astrale token --json -i staging
   $ astrale token --audience worker.example.com --for alice -i staging
 `,
   options: [
@@ -74,6 +97,10 @@ Examples:
     { flags: '--for <identity>', description: 'Mint the token for this identity (alias of --as)' },
   ],
   action: async (opts) => {
-    await tokenCommand(opts as Parameters<typeof tokenCommand>[0])
+    try {
+      await tokenCommand(opts as Parameters<typeof tokenCommand>[0])
+    } catch (error) {
+      failClosed(error, opts as TokenOpts)
+    }
   },
 } satisfies CommandDefinition

package/src/commands/update.ts

@@ -116,26 +116,47 @@ export type StaleReport = {
 }
 
 async function cliStale(opts: UpdateOpts): Promise<StaleReport['cli']> {
+  const running = pkg.version
+  const latest = await fetchNpmLatestVersion().catch(() => undefined)
   try {
     const r = await updateAstrale({
       check: true,
       channel: opts.channel,
       version: opts.version,
-      currentVersion: pkg.version,
+      currentVersion: running,
     })
-    // `check: true` never returns 'updated'; narrow for the type checker.
-    if (r.status === 'updated') return { stale: false, managed: false, current: r.currentVersion }
+    if (r.status === 'updated') {
+      return { stale: false, managed: false, current: running, latest: latest ?? running }
+    }
     return {
-      stale: r.status === 'available',
+      stale: latest !== undefined ? latest !== running : r.status === 'available',
       managed: false,
-      current: r.currentVersion,
-      latest: r.latestVersion,
-      channel: r.channel,
+      current: running,
+      latest: latest ?? r.latestVersion,
+      channel: latest !== undefined ? 'npm' : r.channel,
     }
   } catch {
-    // A package-managed install (or missing metadata) can't self-update — not stale.
-    return { stale: false, managed: true }
+    return {
+      stale: latest !== undefined && latest !== running,
+      managed: true,
+      current: running,
+      ...(latest === undefined ? {} : { latest, channel: 'npm' }),
+    }
+  }
+}
+
+async function fetchNpmLatestVersion(): Promise<string> {
+  const response = await fetch('https://registry.npmjs.org/@astrale-os/cli/latest')
+  if (!response.ok) throw new Error(`npm registry HTTP ${response.status}`)
+  const body: unknown = await response.json()
+  if (
+    body === null ||
+    typeof body !== 'object' ||
+    typeof (body as { version?: unknown }).version !== 'string'
+  ) {
+    throw new Error('npm registry latest document is missing version')
   }
+  return (body as { version: string }).version
 }
 
 async function sdkStale(): Promise<StaleReport['sdk']> {

package/src/commands/view.ts

@@ -522,15 +522,17 @@ What it does:
   an audience-bound credential for shell mounts, and the kernel endpoint.
 
 Examples:
-  $ astrale view /crm/customers/ada                      # views on a node
-  $ astrale view /:crm.acme.dev:view.dashboard           # explicit ViewPath
+  $ astrale view @customer
+  $ astrale view /:crm.example.dev:view.dashboard
   $ astrale view /:agents.astrale.ai:view.agent --target @f00d1234 --as alice
-  $ astrale view /crm/customers/ada --snapshot           # open + show it
+  $ astrale view @customer --snapshot
+  $ astrale view --list
   $ astrale view --sessions ; astrale view --close --all
 `,
   action: async (spec: string | undefined, opts: ViewOpts) => {
     if (opts.close !== undefined) return closeCommand(opts)
     if (opts.sessions) return sessionsCommand(opts)
+    if (opts.list && !spec) return sessionsCommand(opts)
 
     rejectUnrepresentableOverrides(opts)
     if (!spec) return fatal(new Error('Nothing to open — pass a ViewPath or target node.'))

package/src/connection/__tests__/credential.test.ts

@@ -82,6 +82,16 @@ describe('connection credential', () => {
     expect(auth).toBeUndefined()
   })
 
+  test('rejects --as combined with --creds', () => {
+    expect(() =>
+      createCliCredential(
+        { url: `${SOURCE}/invoke`, kernelIssuer: SOURCE },
+        { as: 'alice', creds: 'token' },
+        config,
+      ),
+    ).toThrow('--as cannot be combined with --creds')
+  })
+
   /** @evidence TEST-CLI-CONNECTION-PROPAGATES-AUTH-CANCELLATION */
   test('passes the live Session operation signal to source credential resolution', async () => {
     const controller = new AbortController()

package/src/connection/__tests__/errors.test.ts

@@ -93,4 +93,24 @@ describe('formatKernelError', () => {
       },
     })
   })
+
+  test('maps SDK class names to stable CLI error codes', async () => {
+    const writes: string[] = []
+    const original = process.stderr.write
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      writes.push(typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk))
+      return true
+    }) as typeof process.stderr.write
+    try {
+      const pathError = new Error('Path must have an Id or Domain anchor.')
+      pathError.name = 'PathError'
+      await formatKernelError(pathError, true)
+    } finally {
+      process.stderr.write = original
+    }
+    expect(JSON.parse(writes[0]!)).toEqual({
+      error: 'PATH_INVALID',
+      message: 'Path must have an Id or Domain anchor.',
+    })
+  })
 })

package/src/connection/credential.ts

@@ -94,6 +94,9 @@ export function createCliCredential(
 
 /** Reject contradictory explicit credential selections before identity or network access. */
 export function validateCredentialSelection(options: ConnectionOptions): void {
+  if (options.as !== undefined && options.creds !== undefined) {
+    throw new AstraleError('INVALID_FLAG', '--as cannot be combined with --creds.')
+  }
   if (options.anonymous !== true) return
   const conflicting = [
     ...(options.as === undefined ? [] : ['--as']),