Astrale CLI
astrale conecta-se a Kernels Astrale existentes. Ele seleciona uma instância e
identidade, realiza leituras e mutações de grafos, invoca callables, instala
domínios em execução, lê o journal do Kernel e abre visualizações autenticadas.
A ajuda renderizada do comando é a autoridade para flags e padrões:
astrale --help
astrale <comando> --help
- Binário:
astrale - Pacote:
@astrale-os/cli - Runtime: Node 22 ou mais novo; desenvolvimento com fonte padrão usa Node 26 e também suporta Node 24 e Bun
- Entrypoint de desenvolvimento:
bun cli/bin/astrale.ts <comando>
Superfície de Comandos
Comandos principais:
astrale status
astrale whoami
astrale use <nome>
astrale get <alvo>
astrale query [fontes...]
astrale introspect <origem-ou-caminho>
astrale mutate
astrale call <caminho> [chave=valor...]
astrale token
astrale logs
astrale view [alvo-ou-visualização]
astrale ui ...
astrale instance ...
astrale domain ...
astrale identity ...
astrale auth ...
astrale idp ...
astrale admin ...
Comandos que tocam o Kernel compartilham --format, --json, --raw, --url,
-i/--instance, --timeout, --as, --creds, --anonymous e --debug quando
aplicável. A CLI cria uma Call pública do Kernel, e sua sessão de Cliente possui
roteamento remoto, credenciais novas e uma nova tentativa segura de rota obsoleta.
astrale ui é uma ferramenta de projeto local e não requer Kernel, instância,
identidade ou opções de credencial, exceto astrale ui request, que é um comando
do Kernel autenticado e aceita as opções compartilhadas do Kernel.
Use --anonymous para omitir uma credencial do chamador mesmo quando uma identidade local ou padrão de bookmark existe.
Não pode ser combinado com --as ou --creds; callables necessários rejeitam requisições anônimas.
Projetos UI
Astrale UI é um pacote runtime treeshakeable mais padrão, bloco e fonte de tema de propriedade do consumidor. Inicialize um projeto React e Tailwind CSS v4 com a versão exata publicada da UI:
astrale ui init --preset astrale
astrale ui search "gráfico editável com exportação"
astrale ui request "combobox assíncrono acessível com criação"
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
A inicialização escreve a configuração Base UI + Nova shadcn, importações de tema e preset CSS,
e astrale-ui.lock.json. O lock registra a versão exata do pacote,
tag Git, commit SHA resolvido, versão do shadcn, versão da Base UI, preset e hashes
das fontes instaladas. Metadados de registro, manifestos incluídos e arquivos de item são
sempre lidos desse snapshot de commit único.
Execute astrale ui add sem argumentos de item para um seletor interativo. Em CI,
forneça endereços canônicos explicitamente. A adição comum recusa arquivos instalados
editados localmente; revise esses arquivos, então use --overwrite --yes apenas quando
a substituição for intencional. --dry-run deixa arquivos do projeto e o lock
inalterados. Use astrale ui search <texto-livre> --json para receber uma lista curta de candidatos ranqueada com
código de demonstração exato e seu command ou packageImport de runtime.
Use astrale ui request <texto-livre> quando a pesquisa não atender à necessidade. Ele chama
/:ui.astrale.ai:function.request na instância selecionada com uma intenção limitada (1-512
caracteres) e imprime o recibo retornado: { state: "submitted", requestId, collaborationUrl }
ou { state: "pending" | "outcome-unknown" | "failed" | "conflict", requestId }.
Padrões, blocos e temas são fontes de propriedade da aplicação após a instalação. Um
tema é copiado para components/astrale/theme/ e ativado através de uma importação relativa
na folha de estilo do host configurada; exportações de playground local não requerem
busca de registro ou invocação shadcn. A raiz de composição
className, style inline, valores/ações controlados e anatomia data-slot estável
permanecem abertos ao host. O pacote possui comportamento runtime reutilizável;
nem a CLI nem o SDK incorporam o pacote UI ou a Base UI.
Paths
Use Paths canônicos do Kernel:
| Forma | Exemplo |
|---|---|
| Raiz do domínio | /:notes.example.dev |
| Classe | /:notes.example.dev:class.Note |
| Callable estático | /:notes.example.dev:class.Note:list |
| Callable de instância | @node-id::notes.example.dev:class.Note.method.archive |
| ID do nó | @node-id |
| Atalho do chamador ativo | @self |
Despacho estático usa dois pontos antes do método. Despacho de instância usa :: seguido pela chave completa do Método qualificado por Domínio.
Descubra métodos com astrale introspect <origem> --bundle. Introspecção pode usar um receptor de Classe
para inspecionar um contrato de instância; chamá-lo requer um Path de instância observado.
@self é expandido pela CLI antes da assinatura quando aparece no início de um
Path de chamada ou um valor key=@self simples. Não é reescrito dentro de --data,
stdin JSON, URLs ou substrings arbitrárias.
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
Instâncias e Domínios
astrale instance combina instâncias provisionadas por administradores e bookmarks locais:
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 -i <instância> explícito em scripts. instance delete afeta uma
instância gerenciada por administrador; instance forget remove apenas o bookmark local.
instance status reporta o ciclo de vida de propriedade do Admin por padrão; adicione
--bookmarked para investigar o emissor exato, JWKS e confiança TLS de um bookmark local.
instance invite requer autoridade para gerenciar a Instância exata e concede apenas
acesso de membro da Instância. Retorna o Convite durável imediatamente;
Admin materializa automaticamente acesso Shell filho após aceitação no WorkOS.
instance invitation status <id> realiza uma observação somente leitura do
Convite retido. completed significa que o acesso foi materializado; accepted,
registering e registered são estados intermediários, não acesso completo.
O comando requer o id exato do Convite e não altera seu estado.
instance invitation reconcile <id> é recuperação diagnóstica, não o percurso
normal de convite.
Sem um Domínio Admin implantado, astrale instance list não pode buscar instâncias
gerenciadas (identidades baseadas em chave não têm token Admin). Use
astrale instance list --bookmarked.
Administradores de Frota podem adicionar --include-retired ao inventário Admin comum. O padrão
exclui tombstones de aposentados; Instâncias aposentadas incluídas usam a mesma forma de saída e
são identificadas pelo terminal state: "deleted". O issuer opcional está presente apenas quando Admin
reteve evidência exata. Inalcançável não significa aposentado. Adicione --admin-only quando bookmarks locais
devem ser omitidos do envelope legível por máquina.
instance create provisiona através do Domínio Admin configurado com um chamador WorkOS; Admin possui
a localização do Host. Nem instance create nem instance root import aceitam --host.
instance root import <slug-ou-id> recupera a identidade de assinatura raiz da Instância de propriedade do alvo
através do Admin em uma transferência criptografada de ponta a ponta, de uso único. Importa essa identidade localmente como
<slug>-root, não a identidade raiz do Admin ou do Host. Use --admin <bookmark> ou --admin-url <url>
para selecionar outro endpoint Admin. A recuperação requer