Skip to content

Code

Terminal app

Terminal app

All of Velora, from your shell.

velora is a terminal app that runs the same control plane as the desktop app — the same agents, teams, missions, memory, permissions, and approvals. The interactive session streams agent work into your terminal and pauses for supported approvals. Use the command reference below for the scriptable features.

Install

# the current release, checksummed
curl -fsSL https://github.com/Mehxeo/Velora/releases/latest/download/install-velora-cli.sh | sh

Verifies a SHA-256 checksum, installs to ~/.local/bin, and never asks for sudo. The installer picks Apple silicon or Intel for you.

Also on npm i -g runvelora, brew install mehxeo/tap/velora-cli and scoop install velora-cli. Those three are published separately and can sit a version or two behind the release above.

Standalone binaries include Node and install for the current user. Current macOS desktop installers and standalone CLI binaries are Developer ID signed and notarized. The npm package needs Node 22.5 or newer.

Sign in and update

velora login opens a local sign-in form in your browser. Uppercase letters, symbols, spaces and pasted passwords are accepted. This form signs in to your Velora account; it does not reuse an existing website session. Return to the terminal after sign-in. Use velora whoami to inspect the plan, velora devices to manage slots, velora logout to sign out and velora update to check for an update. For a standalone installation, use velora update --yes to install it. Update npm installations with npm install -g runvelora@latest, then confirm with velora --version.

First five minutes

velora doctor # what can this machine run? velora workspace add ~/code/api # open a project velora login # same account as the desktop app velora run "migrate the users table" --budget 5 velora # the interactive session

In the session, anything that is not a /command starts a task. The agent streams into your terminal, asks inline before risky actions (a allow, d deny), and stops for your review before a branch merges — /accept merges, /reject keeps the branch. Ctrl+C stops the running task.

Choose a project and attach files

Inside velora, enter /workspace to open a searchable project list. Type to filter, use the arrow keys to move, press Enter to select, or Esc to cancel. Choose “Browse for another folder” to navigate folders and select “Use this folder as project”. You can also enter /workspace add ~/code/api to start browsing at a specific folder.

The selection stays active for this session. If you start a task without a selected project, Velora uses an open project containing your current directory, or the only open project. Otherwise it asks you to choose, then continues your original prompt. Coding agents need a project; use an existing Git repository for branch and worktree isolation.

/workspace /workspace api /workspace add "~/code/My App" /files /attach "src/My File.ts" /clear

/files [folder] opens the file picker at the selected project. Enter opens a folder or attaches a file. Use the parent entry to go up, type to filter the current folder, and Esc to cancel. /attach [path] attaches a file directly, or opens the picker when the path is omitted. Relative attachment paths start at the selected project; absolute paths and ~/ paths also work. Enclose paths containing spaces in quotes. Selected files appear above the composer and go to the next task. /clear removes them; switching projects clears them too.

In a shell, list projects with velora workspace, add one with velora workspace add "/absolute/path/My App", and choose it with velora run "explain this project" --workspace api --read-only. The workspace flag accepts a unique name, path, full id, or unique id prefix. Expand ~ outside quotes in shell commands, or use an absolute path inside quotes. --file reads the task prompt from a file; it is separate from session attachments.

If you see “Select a project for this task”, open /workspace and choose the repository. In an older CLI that only lists projects, run velora update --yes for a standalone installation, or pass --workspace to a shell run.

Interactive commands and keyboard controls

Account and setup

/help lists commands; /login signs in through your browser; /whoami shows your account and plan; /agents shows agent availability; /doctor points to the full shell diagnostic.

Projects and files

/workspace [name|path|id] chooses a project; /workspace add [path] browses a new folder; /files [folder] and /attach [path] select files; /clear removes pending attachments; /memory lists workspace memories.

Work and review

/tasks lists recent tasks; /missions lists missions and /missions show <id> shows one; /accept <task> merges reviewed work; /reject <task> keeps its branch.

Activity

/inbox lists unread items; /catchup reports recent activity; /approvals lists pending approvals; /usage shows tokens and spend; /quit or /exit exits.

Enter sends your prompt. Shift+Enter adds a newline on terminals that report that key combination. Up/Down recall prompt history. Tab completes a suggested slash command. Esc clears the composer or cancels a picker. Ctrl+D exits; Ctrl+C cancels a browser login or stops active work, and twice exits while idle. At an approval prompt, press a or y to allow, d or n to deny.

Complete shell command reference

Run velora --help for the command list, or append --help to any command, such as velora missions start --help. Arguments in angle brackets are required; square brackets are optional; an ellipsis accepts several words. --db <path> selects a database, -V / --version prints the version, and bare velora opens the interactive session.

velora login

Sign in to your Velora account in your browser

  • -e, --email <address> — your account email
velora logout

Sign out and forget this device's session

velora whoami

Show the signed-in account, plan, and registered devices

velora devices [action] [deviceId]

List or revoke registered devices (Free: 1 device, Pro: 3)

velora run [prompt...]

Run one task to completion (non-interactive)

  • -w, --workspace <path-or-id> — project to run in (path or id)
  • -a, --agent <provider-id> — agent to use (default: velora-auto)
  • -m, --model <model-id> — model id override
  • --team — run as a Flood team (planner splits the work)
  • --team-size <n> — max active agents
  • --budget <usd> — spend ceiling for this task
  • --read-only — forbid any mutation
  • --yes — allow policy-governed approvals; always-ask actions still require individual approval
  • --json — emit newline-delimited AgentEvents instead of prose
  • --wait-for-capacity — keep waiting when an agent runs out of allowance (default: exit 3)
  • -f, --file <path> — read the prompt from a file
  • --think <level> — fast | balanced | deep
velora q [note...]

Quick capture — start a task with your saved defaults, minimal fuss

  • -w, --workspace <path-or-id> — project to run in (path or id)
  • -a, --agent <provider-id> — agent to use (default: velora-auto)
  • -m, --model <model-id> — model id override
  • --team — run as a Flood team (planner splits the work)
  • --team-size <n> — max active agents
  • --budget <usd> — spend ceiling for this task
  • --read-only — forbid any mutation
  • --yes — allow policy-governed approvals; always-ask actions still require individual approval
  • --json — emit newline-delimited AgentEvents instead of prose
  • --wait-for-capacity — keep waiting when an agent runs out of allowance (default: exit 3)
  • -f, --file <path> — read the prompt from a file
  • --think <level> — fast | balanced | deep
velora tasks

List tasks, and drive them (accept, reject, steer, …)

  • --json — emit newline-delimited JSON instead of a table
  • --page-json — emit a JSON page including its next cursor
  • -n, --limit <n> — page size (1–100)
  • --search <text> — search title and branch
  • --workspace <id> — filter by workspace ID
  • --project <name> — filter by project name
  • --provider <id> — filter by provider
  • --status <status> — filter by task status
  • --cursor <cursor> — continue from the previous page
velora tasks accept <task>

Accept a task in review — merges its branch

velora tasks reject <task>

Reject a task in review — keeps its branch, no merge

velora tasks stop <task>

Stop a running task

velora tasks pause <task>

Pause a task

velora tasks resume <task>

Resume a paused task

velora tasks steer <task> <message...>

Send a mid-flight instruction to a running task

velora tasks show <task>

Show a task's journal (semantic event history)

  • -n, --limit <n> — events to show (1–100)
velora tasks receipt <task>

Inspect verification and landing evidence for a task

velora missions

Autopilot missions — list, start, pause, resume, stop, review

velora missions start <objective...>

Start an Autopilot mission on a project

  • -w, --workspace <path-or-id> — project to run against
  • --budget <usd> — maximum spend
  • --iterations <n> — maximum build iterations
velora missions pause <mission>

Pause a mission

velora missions resume <mission>

Resume a paused mission

velora missions stop <mission>

Stop a mission

velora missions approve <mission>

Approve the latest review checkpoint and continue

velora missions show <mission>

Mission status, constraints, and decisions

velora missions say <mission> <body...>

Add a constraint or goal to a mission's requirement ledger

  • -k, --kind <kind> — goal | constraint | concern | question | idea
velora memory

Workspace memory — architecture, conventions, decisions, known issues

velora memory add <kind> <content...>

Add a memory (kinds: architecture, conventions, decisions, commands, known-issues)

velora memory remove <id>

Remove a memory by id

velora memory import [path]

Import CLAUDE.md / AGENTS.md / GEMINI.md / .cursorrules from a project into memory

velora journal

The semantic event log — what agents did and why

  • -t, --task <id> — filter by task
  • -n, --limit <n> — how many events
  • --json — raw events
velora catchup

What happened while you were away

  • --ack — also acknowledge it (resets the 'away' marker)
velora inbox

Things waiting on you — approvals, reviews, blocks, mentions

  • --filter <kind> — all | unread | approval | blocked | review | mention
  • -n, --limit <n> — page size (1–100)
  • --cursor <cursor> — continue from the previous page
  • --json — emit newline-delimited items with recovery details
  • --page-json — emit a JSON page including counts and its next cursor
velora inbox read <ids...>

Mark inbox items read

velora inbox read-all

Mark every inbox item read

velora approvals

Approvals waiting on you, and the decision history

  • --json — emit newline-delimited JSON instead of a table
velora approvals allow <id>

Allow a pending approval

  • --remember — remember this decision as a permission rule
velora approvals deny <id>

Deny a pending approval

  • --remember — remember this decision as a permission rule
velora approvals history

Past approval decisions

  • -n, --limit <n> — how many
  • --json — emit newline-delimited JSON instead of a table
velora workspace

Open projects the CLI agents can work in

velora workspace add <path>

Open a project folder (a git repo becomes a worktree-isolated project)

velora agents

Agents this machine can run — CLI harnesses and BYO-key models

velora agents disconnect <agent>

Disable an agent without uninstalling it or deleting credentials

velora agents reconnect <agent>

Re-enable an agent without reinstalling it

velora agents models <agent>

Read a provider's live model catalog, defaults, and reasoning capabilities

  • --json — emit complete live model records
velora agents diagnose <agent>

Probe one agent — auth state, models, install health

velora agents test <agent>

Run a real one-turn smoke test against an agent

velora connections

BYO-key model connections (OpenAI-compatible, Anthropic, Gemini)

velora connections add

Register a model endpoint with its API key (key goes to the OS vault)

  • -b, --base-url <url> — endpoint base URL
  • -n, --name <name> — display name
  • -k, --kind <kind> — openai-compatible | anthropic | gemini
  • --wire-format <format> — OpenAI-compatible protocol: chat | responses
  • --default-model <id> — default model id (recommended for large catalogs like OpenRouter)
velora connections remove <id>

Remove a connection and forget its key

velora crews

Named agent teams (who works, with which tools and permissions)

velora crews show <crew>

Print a crew's members and policy

velora crews validate <file>

Validate a crew JSON file against the same rules the desktop enforces

velora workflows

Saved multi-step workflows (DAGs of agents, tools, conditions)

velora workflows runs

Recent workflow runs

  • -n, --limit <n> — how many
velora workflows validate <file>

Validate a workflow JSON file

velora automations

Scheduled and triggered automations

velora automations on <automation>

Enable an automation

velora automations off <automation>

Disable an automation

velora automations run <automation>

Run an automation immediately

velora automations runs

Recent automation runs

  • -n, --limit <n> — how many
velora models

Named model groups (routing pools like "Best Builders")

velora mcp

MCP servers whose tools agents can use

velora mcp add <name> <command...>

Add a stdio MCP server (HTTP/OAuth servers are best added in the desktop app)

velora mcp remove <server>

Remove an MCP server

velora mcp on <server>

Enable an MCP server

velora mcp off <server>

Disable an MCP server

velora doctor

Check this machine: agents found, auth, account, database

  • --install <toolId> — install a missing required tool (ids come from the doctor output)
velora theme [theme] [accent]

Set the CLI look: theme and accent

velora brain [question...]

Velora Brain — built-in AI billed to your account (Free: 10/day)

  • -o, --operation <op> — one of: plan_workflow, repair_plan, optimize_prompt, synthesize_research, interpret_observation, assistant_chat
  • --quota — show today's remaining allowance instead
  • --models — show the backend's available model catalog
  • --model <id> — pin a model from the live catalog
  • --request-id <id> — reuse an existing request identity for a deliberate retry
velora usage

Token and cost totals, budget policies, plan observations

velora settings

Where everything lives, and what this build is

velora update

Check for a newer CLI release

  • --yes — install it when found (binary installs only)
velora serve

Serve the control plane over stdio (the same protocol the desktop speaks)

velora documents

Saved reports and documents in this CLI workspace

  • --json — emit full document summaries
velora documents show <id>

Read a document, including version history with --json

  • --json — emit content, provenance links, and version history
velora documents save <file>

Save a UTF-8 file as a document, or explicitly revise an existing one

  • --title <title> — document title
  • --id <id> — existing document ID to revise
  • --task <id> — originating task ID for a new document
  • --chat <id> — originating chat ID for a new document
velora projects

Work projects (use workspace for code repositories)

  • --json — emit project metadata
velora projects create <name>

Create a Work project

velora projects rename <id> <name>

Rename a project while preserving covers and attachments

velora integrations

Inspect service connections; managed Google authorization is completed in desktop Settings

  • --json — emit integration capabilities and health
velora status

Current task, chat, workflow, and mission activity

Common workflows

velora run "explain the API" --workspace api --read-only velora run --file task.txt --workspace api --budget 5 velora tasks velora tasks show <task-id> velora tasks accept <task-id> velora missions start "fix failing tests" --workspace api --budget 5 velora missions show <mission-id> velora approvals velora approvals allow <approval-id> velora automations runs velora catchup

One-shot runs deny approvals by default. --yes allows policy-governed approvals; always-ask actions still require an individual decision. Use the interactive session for those decisions. --json writes events as newline-delimited JSON. --wait-for-capacity keeps a run waiting for an agent’s allowance to return.

Command groups

run / q

One task to completion — --team for Flood teams, --json for machine-readable events, --yes for unattended runs. q uses your saved quick-capture defaults.

tasks

list, show, accept, reject, steer, pause, resume, stop.

missions

Autopilot: start, pause, resume, stop, approve reviews, and add constraints to the mission ledger.

memory / journal / catchup / inbox

What the work knows, what happened, what needs you.

approvals

Allow or deny pending actions, with --remember to keep the decision as a rule.

crews / workflows / automations

Inspect and validate saved crews and workflows; run and toggle saved automations.

agents / connections / mcp

See what this machine can run; add BYO-key model endpoints and MCP servers.

brain / usage / doctor / update / serve

Built-in AI, spend, machine checks, self-update, and a stdio control-plane mode.

Scripting

velora run "triage the failing CI job" --json | jq 'select(.type=="warning")'

--json emits one event per line. Exit codes: 0 completed or ready for review, 1 failed, 2 cancelled, 3 waiting on allowance.

How it fits with the desktop app

  • Same account, own device slot. The CLI registers as its own device (Free: 1 device, Pro: 3) — manage slots in your account or with velora devices.
  • Independent local state. Tasks created in the CLI stay in ~/.velora; the desktop app keeps its own store. One writer per database, by design.
  • Secrets stay in your OS keychain. Refresh tokens, model keys, and MCP tokens never touch the database.

Need help? Contact Velora support →