Skip to content
valarPublic

About

command line interface for Valar

Topics

Resources

Stars

5 stars

Watchers

1 watching

Forks

Latest commit

 

History

178 Commits

Folders and files

Repository files navigation

Valar CLI

This repository contains the command line interface for Valar.

Getting started

Install via Homebrew

brew install valar/tap/valar

Initial setup

valar config init

The interactive wizard will prompt for your API endpoint, token, and project. For non-interactive usage (e.g. in CI), pass all values as flags:

valar config init --token=[your-api-token] --project=[your-project]

Usage

By default, Valar uses the default valarconfig file in $HOME/.valar/config. If the VALARCONFIG environment variable does exist, valar uses an effective configuration that is the result of merging the files listed in the VALARCONFIG variable.

VALAR_TOKEN, VALAR_ENDPOINT and VALAR_PROJECT take precedence over the active context and the project in .valar.yml, so CI needs no configuration file. Without a configured endpoint, VALAR_TOKEN talks to https://api.valar.dev/v2.

VALAR_TOKEN=... valar build push --wait

Tokens expire. Within 14 days of its token's expiry, a run prints one warning to stderr with the date and where to create a new token. A token that expired or was revoked fails with the server's reason.

Machine-readable output

With --json, or VALAR_OUTPUT=json, every command prints its result as one JSON document on stdout. Lists are arrays of objects whose fields match the API's JSON. Logs (service logs, build logs, build watch, batch logs) are printed as one JSON object per line, progress goes to stderr, and an error is printed on stderr as:

{"error": {"kind": "notFound", "message": "no builds available"}}
valar service list --json | jq -r '.[].name'

Exit codes

Code Kind Meaning
0 Success
1 failed The operation ran and failed, such as a build or deployment
2 invalid Bad arguments, flags or configuration
3 notFound Not found
4 notAllowed Missing or rejected credentials or permissions
5 conflict Conflict with the current state
6 unavailable The server could not be reached or answered with an error

valar build status exits with 1 for any build that is not done.

Configuration

Initialize configuration

valar config init [--token token] [--project project] [--url url] [--name name] [--force]

Dump the current configuration as YAML

valar config view

Print the JSON Schema of .valar.yml

valar config schema

The schema is also checked in at schema/valar.yml.json, for editors. The CLI refuses a .valar.yml with keys the schema does not know, naming the key and its line.

Add an API endpoint

valar config endpoint set [endpoint] --token=[api-token] --url=[endpoint-url]

List configured API endpoints

valar config endpoint

Remove an API endpoint

valar config endpoint remove [endpoint]

Add a configuration context

valar config context set [context] --project=[project] --endpoint=[endpoint]

List configured CLI contexts

valar config context

Set a context as the default one

valar config context use [context]

Remove a configuration context

valar config context remove [context]

Projects

These commands need Valar platform 2.11.0 or newer.

Set up a new project

valar projects create [--public] [project-name]

A project name is 3 to 20 lowercase letters or digits and starts with a letter. Some names are reserved. Each user can create at most 3 projects.

Warning

With --public, anyone can invoke the project's services without a token.

Delete a project

valar projects delete [--yes] [--cascade] [project-name]

Without --cascade, only empty projects can be deleted: a project with services, domains or key-value storage is refused. With --cascade, the project's services are deleted first, then its domain claims. The command asks you to type the project name to confirm; --yes skips that. With --cascade and no terminal to ask on, it refuses unless --yes is given.

Caution

Deleting a project retires its name for good. No one can create a project with that name again, not even you.

Services

Create local configuration

valar service init [--type=[constructor]] [--project=[project-name]] [service]

Without --type, the constructor is detected from the files in the current directory, and the first match wins:

File Constructor
go.mod go
package.json node
requirements.txt or pyproject.toml python
index.html static
Dockerfile docker

The choice is printed to stderr and written to .valar.yml. build push detects the constructor the same way when .valar.yml names none.

Valar supports a variety of constructors. If you are looking for an up-to-date list, please refer to the official documentation.

Tip

Using the --project flag is optional, if it is not defined a value will be inferred from the default project set via the config command or the projects supplied by the API service.

Listing all services in the project

valar service list

Show the logs of the latest deployment

valar service logs [--follow] [--tail] [--skip n] [--all | --deployment n] [--timestamps] [--service service]

--all shows every deployment's log, oldest first, and --deployment one deployment's. --timestamps prefixes each line with the time it was written. With --json, each line is a record such as {"ts": "...", "deployment": "3", "stream": "output", "line": "..."}; platform events have stream: "platform" with event and attrs, and further fields may appear. An older platform yields {"line": "..."} only. Following records reconnects at the end of the log, so lines written while reconnecting can be missed.

Print a service's URLs

Linked custom domains come first, then the service's own <project>-<service> domains.

valar service url [--service service]

Enable a service

Right after a disable, this waits until the old instances have stopped.

valar service enable [--service service]

Disable a service

valar service disable [--service service]

Delete a service

valar service delete [--yes] [service]

Deletes the service with its builds, deployments, batch executions, environment, secrets, schedules and permission rules. Its linked domains are unlinked; the project keeps their claims. The service defaults to the one in .valar.yml. The command asks you to type the service name to confirm; --yes skips that, and without a terminal it refuses unless --yes is given. If a deletion fails, the service stays disabled and running the command again finishes it.

Show and change a service's settings

valar service settings [service]
valar service settings set cpu=500 memory=2048 [--service service]
valar service settings reset memory [--service service]

cpu is in millicores (100 to 2000, in steps of 100) and memory in MiB (128 to 4096). settings shows each value, whether it was set or is the platform's default, its bounds, and the project's budget; with --json it prints the API's response. reset returns a setting to its default. A change takes effect with the next deployment, which pins the settings it runs with. Raising cpu, memory or minRunning needs a token with full access (scope all), within the project's budget; otherwise the command exits with code 4. A value out of its bounds exits with code 2.

A push applies the settings declared in .valar.yml, next to skip:

deployment:
  cpu: 500
  memory: 512

Before a push that deploys, the declared keys are sent as one change, so the push's deployment runs with them; undeclared settings and settings removed from the file keep their value. With --no-deploy or skip: true nothing is sent. http and minRunning are accepted too, but the platform refuses values other than true and 0 for now.

Listing all deployments of a service

valar deployment list

A failed deployment's status names the kind of failure, such as failed (health), on platforms that report it. With --json, the API's failure object is passed through.

Roll out a specific build

valar deployment create [buildid]

Without a build ID, the build of the latest active deployment is redeployed with the service's current runtime variables.

Reverse service to the previous deployment

valar deployment rollback [--delta 1] [--env pinned|current] [--settings pinned|current]

The target is the newest deployment below the live one (the newest done deployment) that served: done or expired, without a failure. Failed deployments, and deployments above the live one, are skipped, and --delta n picks the n-th such deployment. Earlier versions of the CLI picked by version number alone, so they could roll back to a failed deployment.

With --env pinned (the default) the new deployment gets the environment the earlier deployment ran with, and the command names the variables whose values differ from the current ones. With --env current it gets the current variables. --settings works the same way for the service's settings; without it, the platform pins them.

Environment variables

Variables are stored by Valar per service and target: runtime variables reach deployments and batch executions, build variables reach builds. The commands below act on runtime variables; pass --build for build variables or --all for both. Secret values are write-only and never shown again. These commands need Valar platform 2.9.0 or newer.

Set variables

valar env set [--build|--all] [--secret] [key]=[value]...
valar env set [--build|--all] [--secret] [key] < value-file

Given only a key, the value is read from standard input, or prompted for without echo. Prefer that for secrets, since arguments end up in shell history.

Remove variables

valar env unset [--build|--all] [key]...

List variables

valar env list [--build|--all] [--format=(table|raw)]

Show the change log

valar env history [--build|--all]

Move variables from .valar.yml to Valar

valar env import

Older versions kept variables in the environment lists of .valar.yml and sent them with every push. valar env import stores the plain entries as variables, unless they were changed on the service since, names the secrets that have to be set again with valar env set --secret, and empties the lists. Pushes no longer send the lists.

Domains

List all domains attached to a project

valar domains

Add a domain to a project

valar domains add [domain]

Verify a domain

valar domains verify [domain]

Link a domain to a service

valar domains link [--insecure] [domain] ([service])

Caution

If --insecure is enabled, the default HTTP-to-HTTPS redirection handler will be disabled and any plaintext HTTP requests will be forwarded to your service.

Unlink a domain from a service

valar domains unlink [domain] ([service])

Remove a domain

valar domains delete [domain]

Builds

Pushing a new build

valar builds push [--no-deploy] [--service service] [--wait [--timeout 30m]]

push prints the build ID. Unless it skips the deployment, it first applies the settings declared in .valar.yml (see the service's settings). With --wait it also streams the build log to stderr, waits for the build and its deployment, and exits non-zero if either fails. A failed deployment is reported with its kind (build, schedule, capacity, start or health), the reason, the version that keeps serving and the command that reads its log; on a terminal outside CI (CI unset), the last 20 lines of that log are printed too. --service pushes to another service than the one in .valar.yml, with the same build settings.

Listing all builds

valar builds list [prefix]

Listing all builds with the given prefix

valar builds list [prefix]

Inspecting a build

valar builds inspect [prefix]

Abort a specific build

valar builds abort [prefix]

Show logs from build

valar builds logs [--follow] [--raw] [optional buildid]

Watch the build and status until its completed

Exits non-zero if the build fails.

valar builds watch [optional buildid]

Show build status

valar builds status [--exit] [buildid]

Identity

Show the currently authenticated user

valar whoami

Permissions

View permissions

valar auth list

Allow someone to read/write/invoke/manage

valar auth allow [path] [user] [read | write | invoke | manage]

Forbid someone to read/write/invoke/manage

valar auth forbid [path] [user] [read | write | invoke | manage ]

Remove a previously added permission

valar auth clear [path] [user] [read | write | invoke | manage ]

Check someones permission to perform an action

valar auth check [path] [user] [read | write | invoke | manage]

Warning

In case of a public project, this means only the project owner has write, read and invoke access, while any person may invoke a service of the project.

Cron

View the scheduled invokes

valar cron list

Schedule a service invocation

valar cron set [name] [schedule] [--path path] [--data payload] [--service service] [--enabled|--disabled]

Remove a scheduled service invocation

valar cron delete [name] [--service service]

Trigger a cron invoke manually

valar cron trigger [name] [--service service]

Inspect the invocation history

valar cron inspect [name] [--service service]

Agent skill

skills/valar/SKILL.md teaches coding agents to deploy and operate Valar services with this CLI: setup through environment variables, --json output, exit codes, the deploy flow and the app's contract. Install it the way your agent loads skills, for example by copying the skills/valar folder into the agent's skills directory.

About

command line interface for Valar

Topics

Resources

Stars

5 stars

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages