A few concepts explain everything else in Vexly.

Projects

A project is what a repository links to — one project per app, usually. It’s identified by a .vexly file in your project directory:

.vexly holds only the (non-secret) project id and a pointer to the cloud, so committing it is safe — and it’s what lets a teammate clone the repo and start working immediately. The CLI keeps its per-machine bookkeeping outside your project, under ~/.vexly/, so there’s nothing else to manage.

A project is either anonymous or claimed:

• Anonymous — created when you run vexly init without signing in. Anyone who knows the project id can push and pull, so don’t keep anything truly private in an unclaimed project. Anonymous projects are deleted 30 days after their last activity — claim one to keep it.
• Claimed — attached to a workspace and private by default. Only members can access it.

Environments

A project’s secrets are organized into environments — production, development, and any you add. New projects start with development and production; production is the default.

One environment is active at a time (recorded in .vexly). Most commands act on the active environment, and you can target another with --env <slug>:

vexly ls --env production
vexly set FEATURE_FLAG=on --env development

Switch the active environment with vexly env use <slug>; list them with vexly env ls.

Secrets

A secret is a key/value Vexly stores for an environment — the canonical term even when a value isn’t especially sensitive. (When a secret is injected into a process, it becomes an ordinary environment variable — that’s the only sense in which we use that phrase.)

The cloud environment is the source of truth. You manage it directly:

vexly set KEY=value     # add or update a secret
vexly set KEY           # declare a key with an empty value, to fill in later
vexly ls                # list keys (masked)
vexly rm KEY            # remove a secret

When you need the values in a local file — for a tool that insists on .env, or to work offline — pull and push bridge the two:

• vexly pull writes the active environment’s secrets into a local .env.
• vexly push replaces the environment with your local .env.
• vexly diff shows what differs between them.

To use secrets without a file at all, prefer vexly run, which injects them straight into your process.

Workspaces and claiming

A workspace is the team container that owns claimed projects and their members. Signing in and claiming moves a project into a workspace:

vexly login           # sign in through your browser
vexly claim           # attach this project to your workspace

Collaboration is simply workspace membership — invite someone to the workspace (in Studio) and they get access to its projects. There’s no separate “join” step: a teammate is invited, clones the repo (with the committed .vexly), and starts working.

Access: who, and how

Each environment has two independent settings, configured in Studio:

• Visibility — private (workspace members only; the default once claimed) or anonymous (anyone with the project id can pull). Anonymous access is a deliberate opt-in for values that aren’t really secret.
• Access mode — readable (secrets can be pulled into .env) or run-only (secrets can only be injected via vexly run, never downloaded or printed).

Run-only is the stronger guarantee behind agent-safe setup: hand an agent a run-only environment and it can run your app with real secrets but can’t pull the values into its context. Run-only applies to claimed projects only — anonymous projects are always readable.

Next

The quickstart puts these together end to end. Per-command guides for managing secrets, running commands, and requests are coming next.