Astrale CLI
astrale connects to existing Astrale Kernels. It selects an instance and
identity, performs graph reads and mutations, invokes callables, installs
running domains, reads the Kernel journal, and opens authenticated views.
The rendered command help is authoritative for flags and defaults:
astrale --help
astrale <command> --help
- Binary:
astrale - Package:
@astrale-os/cli - Runtime: Node 22 or newer; source development defaults to Node 26 and also supports Node 24 and Bun
- Dev entrypoint:
bun cli/bin/astrale.ts <command>
Command Surface
Primary commands:
astrale status
astrale whoami
astrale use <name>
astrale get <target>
astrale query [sources...]
astrale introspect <origin-or-path>
astrale mutate
astrale call <path> [key=value...]
astrale token
astrale logs
astrale view [target-or-view]
astrale ui ...
astrale instance ...
astrale domain ...
astrale identity ...
astrale auth ...
astrale idp ...
astrale admin ...
Kernel-touching commands share --format, --json, --raw, --url,
-i/--instance, --timeout, --as, --creds, --anonymous, and --debug where
applicable. The CLI creates one public Kernel Call, and its Client session owns
remote routing, fresh credentials, and one safe stale-route retry.
astrale ui is local project tooling and takes no Kernel, instance, identity,
or credential options, except astrale ui request, which is an authenticated
Kernel command and takes the shared Kernel options.
Use --anonymous to omit a caller credential even when a local or bookmark-default identity exists.
It cannot be combined with --as or --creds; required callables reject anonymous requests.
UI Projects
Astrale UI is one tree-shakeable runtime package plus consumer-owned pattern, block, and theme source. Initialize a React and Tailwind CSS v4 project with the exact published UI release:
astrale ui init --preset astrale
astrale ui search "editable chart with export"
astrale ui request "accessible async combobox with creation"
astrale ui add pattern/chart/line-basic
astrale ui add theme/observatory
astrale ui add ./my-playground-export.css
astrale ui doctor
astrale ui doctor --project ./apps/web
astrale ui preset apply compact
Initialization writes Base UI + Nova shadcn configuration, theme and preset CSS
imports, and astrale-ui.lock.json. The lock records the exact package version,
Git tag, resolved commit SHA, shadcn version, Base UI version, preset, and hashes
of installed source. Registry metadata, included manifests, and item files are
always read from that single commit snapshot.
Run astrale ui add without item arguments for an interactive picker. In CI,
provide canonical addresses explicitly. Ordinary add refuses locally edited
installed files; review those files, then use --overwrite --yes only when
replacement is intentional. --dry-run leaves project files and the lock
unchanged. Use astrale ui search <free-text> --json to receive a short ranked candidate list with
exact demo code and its command or runtime packageImport.
Use astrale ui request <free-text> when search does not satisfy the need. It calls
/:ui.astrale.ai:function.request on the selected instance with one bounded intent (1-512
characters) and prints the returned receipt: { state: "submitted", requestId, collaborationUrl }
or { state: "pending" | "outcome-unknown" | "failed" | "conflict", requestId }.
Patterns, blocks, and themes are application-owned source after installation. A
theme is copied to components/astrale/theme/ and activated through one relative
import in the configured host stylesheet; local playground exports require no
registry fetch or shadcn invocation. Composition root
className, inline style, controlled values/actions, and stable data-slot
anatomy remain open to the host. The package owns reusable runtime behavior;
neither the CLI nor the SDK embeds the UI package or Base UI.
Paths
Use canonical Kernel Paths:
| Form | Example |
|---|---|
| Domain root | /:notes.example.dev |
| Class | /:notes.example.dev:class.Note |
| Static callable | /:notes.example.dev:class.Note:list |
| Instance callable | @node-id::notes.example.dev:class.Note.method.archive |
| Node ID | @node-id |
| Active caller shorthand | @self |
Static dispatch uses one colon before the method. Instance dispatch uses :: followed by the complete Domain-qualified Method key.
Discover methods with astrale introspect <origin> --bundle. Introspection can use a Class
receiver to inspect an instance contract; calling it requires an observed instance Path.
@self is expanded by the CLI before signing when it appears at the head of a
call Path or a bare key=@self value. It is not rewritten inside --data,
stdin JSON, URLs, or arbitrary substrings.
astrale get @self --json
astrale introspect /:notes.example:class.Note::notes.example:class.Note.method.archive
astrale call /:blog.example:class.Author:list limit=10
astrale call /:admin.astrale.ai:core.fleet::admin.astrale.ai:class.Fleet.method.listInstances
Instances And Domains
astrale instance combines admin-provisioned instances and local bookmarks:
astrale instance create my-app
astrale instance root import development --yes
astrale instance invite my-app [email protected]
astrale instance invitation status @invitation-id
astrale instance status my-app
astrale instance status staging --bookmarked
astrale instance list --include-retired --admin-only --json
astrale instance use my-app
astrale instance bookmark staging --url https://kernel.example.com
astrale instance forget staging
Use explicit -i <instance> in scripts. instance delete affects an
admin-managed instance; instance forget removes only the local bookmark.
instance status reports Admin-owned lifecycle by default; add --bookmarked
to probe one local bookmark's exact issuer, JWKS, and TLS trust instead.
instance invite requires authority to manage the exact Instance and grants
only Instance member access. It returns the durable Invitation immediately;
Admin automatically materializes child Shell access after WorkOS acceptance.
instance invitation status <id> performs one read-only observation of the
retained Invitation. completed means access is materialized; accepted,
registering, and registered are intermediate states, not completed access.
The command requires the exact Invitation id and does not change its state.
instance invitation reconcile <id> is diagnostic recovery, not the normal
invitation journey.
Without a deployed Admin Domain, astrale instance list cannot fetch managed
instances (key-backed identities have no Admin token). Use
astrale instance list --bookmarked.
Fleet administrators may add --include-retired to the ordinary Admin inventory. The default
excludes retired tombstones; included retired Instances use the same output shape and
are identified by terminal state: "deleted". The optional issuer is present only when Admin has
retained exact evidence. Unreachable does not mean retired. Add --admin-only when local bookmarks
should be omitted from the machine-readable envelope.
instance create provisions through the configured Admin Domain with a WorkOS caller; Admin owns
Host placement. Neither instance create nor instance root import accepts --host.
instance root import <slug-or-id> retrieves the target owned Instance's root signing identity
through Admin over an end-to-end encrypted, one-use transfer. It imports that identity locally as
<slug>-root, not the Admin or Host root identity. Use --admin <bookmark> or --admin-url <url>
to select another Admin endpoint. Recovery require