Cloud quickstart

This quickstart logs the CLI into Verglas Cloud, stores a worker secret, creates a worker from a portable specification, runs it, and checks the result.

Before you begin

You need:

A Verglas Cloud account at verglas.dev.
Git and a Rust toolchain for the current source installation.
A shell on macOS, Linux, or Windows.

The packaged CLI installer is not part of this repository yet. The following source installation matches the current prototype.

Install the CLI

Clone the repository and install the verglas command:

git clone https://github.com/verglas-org/verglas.git
cd verglas
cargo install --path bins/verglas --locked --force
verglas --version

Start the browser authorization flow:

verglas login

The command opens an authorization page and completes through a loopback redirect. A successful login prints the account, tenant, bucket, warehouse, and non-secret credential file paths.Use the device flow on a headless machine:

verglas login --device

Use an API key in automation without putting the key in shell history:

printf '%s' "$VERGLAS_API_KEY" | verglas login --api-key

Login verifies authorization before it writes any file. It stores the control-plane token and scoped lakehouse credentials under ~/.verglas/credentials/, with mode 0600, and updates ~/.verglas/config.toml.

Confirm cloud access

List workers in the tenant:

verglas workers list

An empty list confirms authentication when the tenant has no workers yet. Add --json before the subcommand for machine-readable output:

verglas --json workers list

Store the worker secret

Store an upstream API key. Verglas never returns the stored value:

printf '%s' "$ORDERS_API_KEY" | verglas secrets set ORDERS_API_KEY
verglas secrets list

Worker specifications refer to this value as @secret:ORDERS_API_KEY.

Create a worker specification

Save the following file as orders-worker.toml. The filled example runs every five minutes, targets analytics.orders_raw, and requests 0.25 vCPU with 256 MiB of memory.

orders-worker.toml

spec_version = 1
name = "orders-ingest"
exec = ["python3", "collect.py"]
target_tables = ["analytics.orders_raw"]

[files]
"collect.py" = '''
import json
import os
from pathlib import Path

# Replace this body with the application code that calls the Verglas data
# endpoint or invokes your packaged SDK worker entrypoint.
Path(os.environ.get("RESULT_PATH", "/run/result.json")).write_text(
    json.dumps({"rows": 0, "error": None}) + "\n"
)
'''

[env]
ORDERS_API_URL = "https://api.example.com/v1/orders"
ORDERS_API_KEY = "@secret:ORDERS_API_KEY"

[trigger]
type = "cron"
cron = "*/5 * * * *"

[resources]
vcpus = 0.25
mem_mib = 256

This manifest demonstrates the current portable packaging contract. Use the TypeScript or Rust worker SDK for production table reads and commits. The SDK guides include filled worker code.

Create and run the worker

Create the cloud worker, dispatch one run, and inspect its logs:

verglas workers create --file ./orders-worker.toml
verglas workers get orders-ingest
verglas workers run orders-ingest
verglas workers logs orders-ingest

The run command dispatches the worker once. The cron trigger continues to dispatch runs on the configured schedule.

Develop locally, then push

The same manifest can register on a local server:

verglas workers create --file ./orders-worker.toml --local
verglas workers push orders-ingest

push copies the portable worker specification and bundled files to the cloud. Secret values never travel with the worker. Create each referenced secret in the destination plane before the first run.

Next steps

Read Workers before implementing retries or backfills.
Use the TypeScript SDK to define a fetch-capable worker.
Deploy a service image with Containers.

Get started

Build

SDKs

Reference

Before you begin

Develop locally, then push

Next steps

​Before you begin

​Develop locally, then push

​Next steps

Before you begin

Develop locally, then push

Next steps