@toa.io/cli

Toa Command Line Interface

Common Options

--env

Path to the environment variables file (`.env` format)

--map

Path to the component map (.map.json). Absent, it is looked for from the working directory upwards, as .env is. Required by compose, serve, mono and call.

Development

These commands run a composition, so they need @toa.io/runtime installed beside the CLI, which an application lists in its devDependencies. types and export manifest read manifests only.

compose

Run composition.

toa compose [paths]

paths Glob patterns to look for components.
--kill Shutdown composition after it's started
--service Extension service to run in this composition, by shortcut or package reference. Repeat for several.
--dock Run in Docker using current .env.
--context Path to the Context root (default .).

Note that your localhost it is accessible from a container as host.docker.internal.

--service starts the named extension services in the composition process, beside its components:

$ toa compose ./components/* --service exposition --service configuration

The list is exact — unlike mono, nothing is discovered. A service the named ones talk to answers over the network in a deployment; in one process it is named too, or nothing answers it. Absent --service, the list is read from TOA_SERVICES, whitespace-separated, which is what a deployment sets from a composition's services.

serve

Run an extension service.

toa serve [paths...]

paths Path, package reference, or shortcut of an extension (default .). Several in one process.

$ toa serve exposition
$ toa serve exposition configuration
$ toa serve ./extensions/exposition @toa.io/extensions.configuration

The list is exact — unlike mono, nothing is discovered. A service the named ones talk to answers over the network in a deployment; in one process it is named too, or nothing answers it. One named that has no service in this environment, because its variables are absent, is refused, and nothing runs.

types

Generate types for a Context and every component in it.

toa types

--path Path to the Context root (default .).
--environment Environment the Context is read for, including foo:bar as toa env.
--quiet Print nothing.

Written are types/ beside context.toa.yaml and a types.ts beside every component's manifest. Both are Toa's: every run rewrites them, and each carries the package.json naming it — @components/<directory> for a component, the Context's own name for the Context.

What a manifest does not state is not generated. An operation declaring no output returns unknown, unless it is one Toa itself provides — the prototype's algorithms return the scope they are given. The Context every component shares always has env, name, instance, atom, local and remote; what an extension puts on every component — telemetry, fetch — is there too. An alias for something a schema does describe belongs in a file of your own:

import type { Entity } from '@components/activities'

type Plugin = Entity['plugins'][number]

mono

Run composition and extension services in one process.

Application components are found by manifest.toa.yaml, same as compose. Extension services are started for each component extension whose Factory implements service().

toa mono [paths...]

paths Glob patterns to look for components (default .).
--kill Shutdown after it's started.

Environment variables must be provided as with compose and serve (typically via toa env / --env).

call

Call endpoint.

toa call <endpont> [request]

endpoint endpoint to call.
request Request object.

$ toa call dummies.dummy.create "{ input: { name: 'foo' } }"

The endpoint is called as the map describes it, so a map is read the way compose reads one.

env

Export environment to a .env file.

toa env [environment]

environment deployment environment name (default local). foo:bar uses @foo, then @bar, then the unsuffixed key; the running environment is foo. The chain is not stored.
--path path to a Context (default .)
--as output file path (default .env)
--interactive prompt for secret values
--dev / -d fill secrets with local/dev defaults; unresolved secrets throw unless --interactive is also set
--component / -c generate variables only for this component, everything needed to run it, including when it is evicted. Repeat for several
--service / -s generate variables only for this service, by shortcut or package reference. Repeat for several

Credentials specified in the output file are preserved.

It is recommended to add .env* to .gitignore.

map

Export the components of a Context to a .map.json file.

toa map [environment]

environment deployment environment name (default local), as env reads it.
--path path to a Context (default .)
--as output file path (default .map.json)

Every component of the Context — its own, the ones its extensions bring, and the ones it evicts — with the version it runs and what that version provides:

{
  "default.orders": {
    "version": "3f9a1c02",
    "entity": { "properties": { "sum": { "type": "number" } }, "required": ["sum"] },
    "operations": {
      "transit": { "type": "transition", "scope": "object", "bindings": ["@toa.io/bindings.amqp"] }
    },
    "events": { "created": { "binding": "@toa.io/bindings.amqp" } }
  }
}

A process is started with one, and is held to what it states. See contracts.

Run it again when a component's sources change: a version is a hash of them, and a composition whose component the map states another version of is refused at boot.

It is generated, so add .map.json to .gitignore beside .env*. A committed one is true of the sources it was written from and of no others.

export manifest

toa export manifest

Print normalized manifest.

--path path to a component (default .)
--error print errors only
--output output format (default yaml)

export secrets

toa export secrets <environment>

Print deployment secrets. environment is the same form as toa env.

--path path to context (default .)

export convergence

toa export convergence <environment>

Print what the region's convergence broker must carry: an exchange pair and a durable queue per component the context converges. Declaring them is not this command's to do — a pointer carries no credentials, and the region being prepared has nothing deployed on it yet — so the output is piped into the broker's definitions import:

$ toa export convergence eu | curl -u <user>:<password> \
    -H 'content-type: application/json' -X POST --data @- \
    http://<broker>:15672/api/definitions

environment is the same form as toa env.
--path path to context (default .)
--format definitions (default) or commands, which prints rabbitmqadmin invocations instead

export image tags

toa export tags <environment>

Print image tags. environment is the same form as toa env.

--path path to context (default .)

Operations

These commands need @toa.io/operations installed beside the CLI, and nothing of the runtime: see installing. Some use the current kubectl and docker context.

build

Build Docker images.

toa build

--path path to a Context (default .)
--mono build a single image that runs toa mono

push

Build Docker images and push them to the registry.

toa push [environment]

environment deployment environment name (default default), including foo:bar as toa env.
--path, -p path to the context (default .).

An image that the registry already has is skipped, so a push of the sources a release is made of leaves that release nothing to build.

deploy

Deploy a Context.

• Build Docker images.
• Push Docker images to the registry.
• Build a Helm chart.
• Apply the Helm chart to the current Kubernetes context.

toa deploy [environment]

environment deployment environment name (default default), including foo:bar as toa env.
--path path to a Context (default .)
--namespace Kubernetes namespace to apply the Helm chat to
--wait wait until all Pods [are ready](https://helm.sh/docs/intro/using_helm/#helpful-options-for-installupgraderollback)
--dry do not apply the Helm chart
--mono build one image and deploy it as a single Deployment

toa build --mono and toa export deployment --mono use the same layout.

Optional mono: in the context sets replicas and resources (environment-suffixed as mono@dev):

mono:
  replicas: 2
  resources:
    cpu: [200m, 2]
    memory: [256Mi, 2Gi]

Without mono:, --mono defaults to 2 replicas and no resource requests or limits.

conceal

Deploy a generic Kubernetes secret with the prefix toa-.

toa conceal <secret> <key-values...>

secret Secret name.
key-values List of keys and values of the secret as key=value.
--namespace Kubernetes namespace where the secret should be deployed.
--interactive prompt for secret values
--environment environment name for interactive mode, including foo:bar as toa env.
--path path to a context for interactive mode

If a secret already exists, then given key-values will be added to it.

Example

$ toa conceal bindings-amqp-default username=developer password=secret

reveal

Outputs keys and values of a secret.

toa reveal <secret>

shell

Run interactive shell inside a disposable pod inside a Kubernetes cluster.

toa shell [image]

image Docker image to Run (default alpine).

Examples

$ toa shell mongo
$ toa shell -- ping 1.1 # extra arguments can be passed

key

Generate a 256-bit base64url JWE encryption key. Use --format paseto only for legacy PASETO-compatible keys.

toa key
toa key --format paseto
toa key --public

The default output can be used in an identity.tokens.keys entry with format: jwe or with the format omitted. --format paseto generates a V3.local PASERK value for a transitional format: paseto entry. --public generates a PASETO V3.public secret/public pair and ignores the symmetric key format.

toa key

--public boolean generate a public/private key pair.
--format jwe | paseto secret key format (default: jwe).