> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verglas.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud quickstart

> Log in to Verglas Cloud and deploy a scheduled worker from the CLI.

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](https://verglas.dev).
* Git and a Rust toolchain for the current source installation.
* A shell on macOS, Linux, or Windows.

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

<Steps>
  <Step title="Install the CLI">
    Clone the repository and install the `verglas` command:

    ```bash theme={null}
    git clone https://github.com/verglas-org/verglas.git
    cd verglas
    cargo install --path bins/verglas --locked --force
    verglas --version
    ```
  </Step>

  <Step title="Log in">
    Start the browser authorization flow:

    ```bash theme={null}
    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:

    ```bash theme={null}
    verglas login --device
    ```

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

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Confirm cloud access">
    List workers in the tenant:

    ```bash theme={null}
    verglas workers list
    ```

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

    ```bash theme={null}
    verglas --json workers list
    ```
  </Step>

  <Step title="Store the worker secret">
    Store an upstream API key. Verglas never returns the stored value:

    ```bash theme={null}
    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`.
  </Step>

  <Step title="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.

    ```toml orders-worker.toml theme={null}
    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
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Create and run the worker">
    Create the cloud worker, dispatch one run, and inspect its logs:

    ```bash theme={null}
    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.
  </Step>
</Steps>

## Develop locally, then push

The same manifest can register on a local server:

```bash theme={null}
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](/docs/platform/workers) before implementing retries or backfills.
* Use the [TypeScript SDK](/docs/sdk/typescript) to define a fetch-capable worker.
* Deploy a service image with [Containers](/docs/platform/containers).