This repository contains the command line interface for Valar.
brew install valar/tap/valarvalar config initThe 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]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 --waitTokens 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.
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'| 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.
valar config init [--token token] [--project project] [--url url] [--name name] [--force]valar config viewvalar config schemaThe 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.
valar config endpoint set [endpoint] --token=[api-token] --url=[endpoint-url]valar config endpointvalar config endpoint remove [endpoint]valar config context set [context] --project=[project] --endpoint=[endpoint]valar config contextvalar config context use [context]valar config context remove [context]These commands need Valar platform 2.11.0 or newer.
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.
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.
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.
valar service listvalar 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.
Linked custom domains come first, then the service's own <project>-<service> domains.
valar service url [--service service]Right after a disable, this waits until the old instances have stopped.
valar service enable [--service service]valar service disable [--service 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.
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: 512Before 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.
valar deployment listA 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.
valar deployment create [buildid]Without a build ID, the build of the latest active deployment is redeployed with the service's current runtime variables.
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.
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.
valar env set [--build|--all] [--secret] [key]=[value]...
valar env set [--build|--all] [--secret] [key] < value-fileGiven 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.
valar env unset [--build|--all] [key]...valar env list [--build|--all] [--format=(table|raw)]valar env history [--build|--all]valar env importOlder 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.
valar domainsvalar domains add [domain]valar domains verify [domain]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.
valar domains unlink [domain] ([service])valar domains delete [domain]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.
valar builds list [prefix]valar builds list [prefix]valar builds inspect [prefix]valar builds abort [prefix]valar builds logs [--follow] [--raw] [optional buildid]Exits non-zero if the build fails.
valar builds watch [optional buildid]valar builds status [--exit] [buildid]valar whoamivalar auth listvalar auth allow [path] [user] [read | write | invoke | manage]valar auth forbid [path] [user] [read | write | invoke | manage ]valar auth clear [path] [user] [read | write | invoke | manage ]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.
valar cron listvalar cron set [name] [schedule] [--path path] [--data payload] [--service service] [--enabled|--disabled]valar cron delete [name] [--service service]valar cron trigger [name] [--service service]valar cron inspect [name] [--service service]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.