Skip to main content
Open console

The Vallic CLI

Install the command line and use it for deploys, shells, files, databases, backups, variables, domains, the CDN and the team.

6 min read

The vallic command does from a terminal what the console does in a browser. It also opens a shell in a container, streams a database in or out, and opens a local port onto a service.

Installing it

curl -fsSL https://raw.githubusercontent.com/Vallic/vallic-cli/main/installer.sh | bash
vallic login

vallic login opens a browser to sign you in. In CI, sign in with a token from your account: vallic login --token. A token deploys and follows deploys and nothing else: see What a token can do.

Shell, database and file commands also need an SSH key on your account. Add it with vallic ssh-key add: see Shell access.

vallic self-update replaces the binary with the version the platform publishes.

Which project and environment

Inside a checkout of your project, the CLI takes the project from the git remote and the environment from the branch, so most commands need neither. Elsewhere, name the environment and add --project with the project's machine name:

vallic ssh staging --project acme-site

A branch that matches no environment is refused.

Examples

Getting set up

# Who the stored credential belongs to
vallic whoami

# Put your SSH key on your account: ~/.ssh/id_ed25519.pub, or the one you name
vallic ssh-key add
vallic ssh-key list

# Record which project this checkout is, once, outside a clone of its repository
vallic link acme-site

# What this checkout points at: project, environment, branch, last deploy
vallic status

# Check vallic.yaml before committing it
vallic validate --against production

Environments

# Every environment of the project, and one in full
vallic env list
vallic env info staging

# A development environment from a branch, deployed on every push
vallic env create feature/checkout --type development --auto-deploy

# Point staging at another branch
vallic env source staging --branch release/2.0

# Its address, or open it in the browser
vallic url staging --open

# Behind its offline page while something is fixed, and back
vallic env maintenance on staging --note "Back at 15:00"
vallic env maintenance off staging

Deploying

# Deploy what staging's branch points at, and wait for the result
vallic deploy staging --wait

# Build and deploy in one go
vallic build staging --deploy

# The last five builds, and deploy an earlier one
vallic release list production --limit 5
vallic deploy production --release 41 --wait

# Deploy what is already live again, or put the previous release back
vallic redeploy production --wait
vallic rollback production --wait

What the platform has been doing

# Recent deploys and builds, and one task's output as it runs
vallic activity list production --type deploy,build
vallic activity log 1234 --follow

# Call off a deploy still waiting in the queue; one already running finishes
vallic activity cancel 1235

# The site's own logs: a live tail, a window, one kind, into a file
vallic logs production --follow
vallic logs production --since 1h --source proxy
vallic logs production --since 24h --output production.log.gz

# CPU, memory and disk: now, on average and at peak, over a day or longer
vallic metrics production
vallic metrics production --window 7d

A shell and commands

# A shell in the site's container
vallic ssh staging

# One command, then back
vallic ssh staging -- ls -la /mnt/files/public

# drush, in a Drupal project
vallic drush staging -- cr
vallic drush production -- updb -y

On an environment with several machines, --machine names the machine. Without it the login goes where the site runs. --container opens a worker's container instead of the site's:

vallic ssh production --machine web-2
vallic ssh production --container worker-queue-1 -- php artisan queue:failed

Files

# Public files up, and back down
vallic mount upload staging ./files
vallic mount download production ./files-from-production

# Private files, and a mount vallic.yaml declares
vallic mount upload staging ./private --area private
vallic mount upload staging ./exports --area mounts/exports

# Every area an environment has, by the name --area takes
vallic mount list staging

Databases

# A copy of production's database, in a file named for it, then onto staging
vallic db dump production
vallic db import staging --file acme--production--dump.sql

# Compressed, with the time in the name so the last one is kept
vallic db dump production --gzip --timestamp

# Part of it: some tables, all but some, or the schema alone
vallic db dump production --table users --table orders
vallic db dump production --exclude-table cache_render,sessions
vallic db dump production --schema-only

# How much it holds, and its largest tables
vallic db size production

# A stream, for a pipeline
vallic db export production --gzip > production.sql.gz
vallic db import staging < production.sql

# An interactive prompt, or one query
vallic sql staging
vallic sql production -- 'SELECT COUNT(*) FROM users'

# A local port onto the database, for a desktop client
vallic tunnel staging db --port 3307
  • db dump names the file after the project and the environment: acme--production--dump.sql.
  • db dump writes the file only once the dump is whole: a dump that fails half way leaves nothing that looks like a good one.
  • db import decompresses a gzip dump on its own, from a file or standard input.
  • Table names are exact: there are no wildcards.

Backups

# The database backups production has, and take one now
vallic backup list production --kind database
vallic backup create production --kind database

# A copy of one to keep, and put the newest back over the environment
vallic backup download 42 production --wait
vallic backup restore latest staging --kind database

backup restore overwrites the environment with its own backup. A backup goes back only where it was taken. On production an owner has to confirm it in a browser.

Variables

# What is in effect for staging, including the project's
vallic var list staging

# Set a secret, read a value, and restart the site so it takes effect
vallic var set PAYMENT_KEY sk_live_example production --secret
vallic var get API_URL staging
vallic var apply production

# Add every variable in a .env, all or none; see first what it would add
vallic var import .env.production production --dry-run
vallic var import .env.production production

var import adds and never replaces: a name already set refuses the whole file. Names that read like credentials are stored as secrets unless --secret names exactly which ones are.

Domains

# Claim a hostname, then check the DNS records it printed
vallic domain add shop.example.com production
vallic domain verify shop.example.com production

# Make it the site's address: the platform hostname redirects to it
vallic domain primary shop.example.com production

# Or redirect every other hostname to it as well
vallic domain canonical shop.example.com production

See Primary and canonical for what each redirects.

The CDN

# What it caches, and for how long, and emptying it
vallic cdn show production
vallic cdn clear production

The team

# Who is in it, and the invitations still waiting
vallic team people

# Invite somebody; the link is printed once and no mail is sent
vallic team invite ana@example.com --role developer
vallic team invite contractor@example.com --role developer --projects acme-site

# Another role, or take somebody off
vallic team role ana@example.com admin
vallic team remove contractor@example.com

The team is the one vallic team switch chose, or --team. See Teams for what each role may do.

Coming from Upsun

Upsun's and Platform.sh's noun:verb spelling works: vallic db:dump, vallic environment:list and vallic mount:upload. The few commands spelled differently here are mapped: db:sql is sql, user:add is team invite, self:update is self-update.

Every command has --help, with more examples than these.

Next

  • Shell access: keys, plain SSH, and what the shell can reach
  • Variables: scopes, secrets and when they take effect
Need a hand?

Open a ticket from Support in the console. We answer on the ticket.

Open the console How support works