From astrale
Reference for the Astrale CLI (binary `astrale`, package `@astrale-os/astrale`) - CLI setup, command composition, graph exploration and querying, kernel calls, instance bookmarks and admin-provisioned instances, identity management, delegation tokens, browser sessions, output behavior, debugging, and local storage.
How this skill is triggered — by the user, by Claude, or both
Slash command
/astrale:astrale-cliThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
`astrale` is the CLI for connecting to Astrale kernels. It authenticates,
astrale is the CLI for connecting to Astrale kernels. It authenticates,
selects an instance, calls kernel operations, inspects graph nodes, mints
delegation tokens, and prepares authenticated browser sessions for agents.
The command surface lives in the code. Use astrale --help and
astrale <cmd> --help as the source of truth for commands, flags, defaults,
and examples. This skill should only hold cross-cutting model details and
common recipes that help compose those commands correctly.
astrale@astrale-os/astralebun cli/bin/astrale.ts <command>Current top-level commands:
astrale whoami
astrale use <name>
astrale update
astrale call <path> [params...]
astrale token
astrale get <path>
astrale ls [path]
astrale describe <path>
astrale query <cypher>
astrale logs <service>
astrale status
astrale browser
astrale instance ...
astrale domain ...
astrale admin ...
astrale identity ...
astrale auth ...
astrale idp ...
Command groups:
| Group | Commands |
|---|---|
| Kernel | call, token, get, ls, describe, query, logs |
| Context | status, whoami, use |
| Management | admin, instance, domain, identity, auth, idp, update |
| Agent | browser |
Shared kernel options are merged onto kernel-touching commands at registration
time: --format, --json, --raw, --url, -i/--instance, --timeout,
--as, --creds, and --debug. Check astrale <cmd> --help before relying
on an option for a specific command.
Clients address graph entities and operations with Paths.
| Form | Grammar | Use when |
|---|---|---|
| Absolute path | /domain, /domain/class.Name, /domain/interface.Name | Domain, Class namespace, or Interface namespace |
| Static method | /:domain:class.Name:method or /domain/class.Name/method | Class-level or interface-level operation |
| Instance method | <nodePath>::method or @id::method | Operation on a node instance |
| Id reference | @nodeId | Reference a node by UID |
| Self reference | @self | CLI-side shorthand for the active caller node |
Load-bearing rules:
class. or interface. prefix in namespace segments:
/:host.astrale.ai:class.KernelInstance:list, not
/:host.astrale.ai:KernelInstance:list.::; single colon is for domain-path
static method syntax./:domain:class.Name:method for static calls
when possible. It resolves by domain membership rather than tree layout.@<id> takes a graph node UUID only — @<slug> is NOT_FOUND. And a
permission error naming a node that "should exist" often means the node
does NOT exist (missing targets surface as permission denied, not
NOT_FOUND) — verify with astrale get <path> before chasing grants.Examples:
astrale call /:blog.acme.com:class.Author:list
astrale call /:blog.acme.com:interface.NoteOps:createNote title=Hello
astrale call /blog.acme.com/alice::deactivate
astrale call @f00d...::deactivate
@self is a CLI-side literal expanded before a call is signed and sent. It
resolves to the active identity's registered node id on the target instance.
The kernel receives the concrete @<nodeId> value.
Supported positions:
@self, @self::method, @self/childkey=@self, key=@self::methodNot expanded:
--url--dataprefix@self@self,@otherFor JSON payloads, resolve manually before building the payload.
astrale describe @self
astrale call @self::deactivate
astrale call /:d:class.X:m owner=@self
If @self expands to a deleted or stale id, refresh the registration with
astrale identity register <name> -i <instance>.
For IdP-backed identities (astrale auth login), @self just works: on the
first use against an instance the CLI does ONE kernel whoami round-trip,
caches the node id as a registration, and expands locally afterwards. If that
lookup fails (offline, expired session), the error carries the manual recipe:
astrale call "/:kernel.astrale.ai:interface.Identity:whoami" --json # → { id }
astrale describe @<that-id>
astrale instance manages admin-provisioned instances and local bookmarks.
Use:
astrale instance create my-app
astrale instance status my-app
astrale instance use my-app
astrale instance active
astrale instance bookmark staging --url https://kernel.example.com
astrale instance forget staging
Important distinctions:
instance use changes the active target instance.instance active shows the active target instance.instance bookmark records an existing remote kernel URL locally.instance forget removes a local bookmark only.instance delete is destructive for admin-managed instances.-i <instance> over relying on ambient active
instance state.The astrale CLI is connect-only — it does not build, run, or deploy
domains. The astrale domain group manages the admin catalog and installs a
running domain onto an instance (list, publish, install); it does NOT
build or run domains. astrale domain list shows the published catalog (add
--check to probe each URL's reachability, --default-only for the
install-on-every-instance set, -q to pipe install URLs). Building, running,
and deploying live in two separate tools:
create-astrale-domain scaffolds a new standalone domain project
(pnpm create astrale-domain <slug>), writing an astrale.config.ts.astrale-domain (the @astrale-os/sdk bin, behind the project's
pnpm dev / pnpm prod scripts) runs dev | prod | deploy <env> | build.Domains are installed by URL or catalog origin, never from a file (there is
no committed spec.json). astrale domain install has two modes:
astrale domain install <origin|url> -i <slug>
installs a PUBLISHED domain through the admin control plane
(DomainEntry.install), addressed by its catalog origin (the unique
registry key) or url. Run it bare to pick from the catalog interactively.
The target instance is the active one or -i <slug> and must be
admin-managed (otherwise it fails loudly and points you at --direct).--direct — astrale domain install <url> --direct installs a url
straight onto the instance kernel (Root.installDomain), bypassing the
catalog. Works on ANY instance you can authenticate to (managed, bookmarked,
or local), using your own authority, and is the only mode that runs the
identity-override consent gate. Use it for dev/local instances and
freshly-deployed, not-yet-published workers.With the managed (astrale) adapter, pnpm prod publishes the bundle
through the platform AND installs it on the configured instance in one step —
no manual domain install. The service serves at
https://<name>-<hash>.svc.<region>.astrale.ai (the CLI session is the auth).
For authoring domains end-to-end (schema, handlers, external APIs, deploys), load the astrale-domain skill; for graph-level schema surgery on a live kernel, astrale-live-domain-edit.
Keep the auth model simple:
astrale auth login authenticates with an IdP and stores an IdP-backed local
identity/session.astrale identity create <name> creates a local key-backed identity.astrale identity register <name> -i <instance> registers that identity with
a target instance.astrale use <name> switches the active identity or active instance when the
name is unambiguous. Use --identity or --instance when it is ambiguous.--as <identity> makes a kernel command call as that identity.--creds <token> sends an already minted credential and skips normal signing.Useful checks:
astrale status
astrale whoami
astrale auth status
astrale identity list
astrale identity whoami
astrale auth token --raw prints a cached IdP provider token for shell use.
That is different from astrale token, which mints a delegation token for
kernel/worker calls.
IdP sessions refresh themselves: every kernel command silently exchanges the
refresh token when the cached access token is stale, and concurrent astrale
processes serialize that exchange on a per-identity file lock (refresh tokens
are single-use — the lock is what makes parallel agent-driven commands safe).
One astrale auth login should therefore last until the IdP itself ends the
session. Access tokens are also cached per audience, so alternating
commands between instances does not burn a refresh per flip.
Refresh failures come in two distinct flavors — read the error before re-authenticating:
An agent driving the CLI needs no special flow: it shares ~/.astrale, so one
human astrale auth login is enough and every subsequent command (including
parallel ones) self-refreshes. For fully headless setups with no human login,
use a key-backed identity — astrale identity create <name> then
astrale identity register <name> -i <instance> — which signs locally and
never expires; or hand the agent a TTL-bound delegation token minted with
astrale token and passed via --creds.
astrale token mints a delegation token for the active instance and identity.
Use it when another process, script, or worker needs to call with delegated
authority.
Common flow:
export TOKEN=$(astrale token --audience dist.astrale.ai --raw)
astrale call /:dist.astrale.ai:class.Domain:install \
--url https://dist.astrale.ai \
--creds "$TOKEN" \
-d '{"name":"alice"}'
Notes:
--audience <aud> should match the receiving service or worker expectation.--for <identity> is an alias for --as <identity>.--raw when assigning the token to an environment variable.--json when a machine should parse token metadata.Use these commands for graph inspection:
astrale ls /
astrale get /some/path
astrale describe /some/path
astrale query 'MATCH (n) RETURN n LIMIT 5'
astrale call <path> --describe
Admin host records are exposed by the concrete provider class, not by the
provider-neutral Host interface:
astrale call /:admin.astrale.ai:class.ScalewayVPS:list -i admin --json
astrale call /:admin.astrale.ai:class.ScalewayVPS:list --describe -i admin
Gotchas:
query is read-only; the kernel rejects write keywords such as CREATE,
DELETE, SET, MERGE, REMOVE, and DETACH.describe can return large properties such as serialized schemas. Pipe to
jq or use command-specific flags when available.ls has list-specific output controls such as -q/--quiet, --count, and
-l/--long; check astrale ls --help.astrale call <path> --describe before
executing a call you are unsure about.class.<Name> materializes as a Folder node (kind Folder, name
prefixed class.) whose children are the class's callable Functions. There
is no Class node at that tree position — the Class definition lives inside
the Domain's serialized schema prop. So --filter Class returns zero; use
--filter Folder, or descend into class.<X> and filter on Function.Output is selected from stdout shape and flags:
--json, or --raw: machine-oriented output.--json: always valid JSON for tools like jq.--raw: unwrap scalars for shell assignment and write raw bytes for binary
responses.--format yaml|json: explicit structured output where supported.call --output <file> writes binary/raw output to a file.astrale call; stdin on a TTY is ignored.--data takes precedence over stdin and key=value params.key=value values are auto-coerced: true/false/null, numeric strings
→ numbers, {…}/[…] → parsed JSON; everything else stays a string. To
force a digits-only STRING (or pass nested values), use --data.echo "$PAYLOAD_JSON" | astrale call <path> --json.Examples:
astrale ls / --json | jq .
TOKEN=$(astrale token --audience dist.astrale.ai --raw)
astrale call /:d:class.Asset:render id=123 --output asset.png
astrale call /:d:class.X:m -d '{"name":"alice"}'
Use astrale browser to prepare an authenticated GUI browser session that an
agent can drive with agent-browser.
Install once:
npm install -g agent-browser && agent-browser install
npx skills add vercel-labs/agent-browser
Connect and verify:
astrale browser
astrale browser --check
astrale browser --login
astrale browser --cdp 9222
After astrale browser connects, it prints the exact agent-browser --profile
command to use. Driving the page is agent-browser's job:
agent-browser --profile <dir> snapshot
agent-browser --profile <dir> open <url>
agent-browser --profile <dir> click @e3
agent-browser --profile <dir> eval '<js>'
The GUI session uses an httpOnly cookie. There is no token-injection shortcut; the persistent browser profile is the session boundary.
Start with local context:
astrale status
astrale admin status
astrale instance active
astrale auth status
astrale whoami
Use diagnostics:
--debug to kernel commands for full error diagnostics — including
the server-side cause chain (data.cause), which shows the ROOT failure
inside wrapped errors (e.g. what actually failed under a
Delegation mint failed or KERNEL_ERROR).--log-level debug for verbose CLI logging.--log-format json when an agent or script should parse logs.--json or --raw for structured command output.--ci and --no-prompt in non-interactive automation.--timeout <ms> when a kernel call is valid but slow.astrale logs <service-slug> [--tail N] to tail a MANAGED SERVICE's
runtime logs — console output, 5xx accesses, and uncaught exception stacks
(the readable side of internal error; reference = … responses). The slug
is the first label of the service's …svc.<region>.astrale.ai URL (also
accepts the full URL). In-memory, last ~500 lines, resets on runtime
restart; services deployed before log capture need one redeploy.Common error classes and first checks:
| Error shape | First check |
|---|---|
| Connection error | astrale status; verify the instance URL and network path |
| Authentication error | astrale auth status, astrale whoami, active identity |
| Permission denied | Does the named node actually exist (astrale get)? Then active identity and target operation permissions |
| Not found | Path spelling, active instance, installed domain |
| Validation error | astrale call <path> --describe |
| Timeout | Target availability and --timeout <ms> |
If a command fails only in a script, compare TTY vs non-TTY behavior and pass
explicit --json, --raw, -i <instance>, and --as <identity> as needed.
CLI state lives under ASTRALE_HOME when set, otherwise ~/.astrale.
Core paths:
~/.astrale/
config.json CLI and admin config
install.json Script-install metadata for `astrale update`
instances.json Active instance and local instance records
identities.json Active identity and identity metadata
idps/ IdP provider metadata
idp-sessions/ Cached IdP sessions
keys/ Local identity keypairs
data/ Local data directory used by local adapters
browser.json Last connected GUI browser session
browser/<host>/ Persistent browser profile for GUI auth
Optional overrides:
ASTRALE_HOME: root for CLI state.ASTRALE_KEYS_DIR: keypair directory.ASTRALE_DATA_DIR: data directory.Keep storage references centralized in this section. Other sections should describe behavior, not repeat file locations.
cli/bin/astrale.tscli/src/program.tscli/src/registry.ts, cli/src/command.tscli/src/commands/cli/src/lib/cli/src/kernel/cli/src/commands/__tests__/Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub astrale-os/cli --plugin astrale