| name | evidence-cli |
| description | Evidence.dev CLI commands, project setup, deployment configuration — dev server, build, rendering modes, environment variables, deployment platforms |
| version | 1.0.0 |
When to use
Invoke when the user asks to:
- Run Evidence.dev commands ("run sources", "build the project", "start dev server", "deploy")
- Configure npm scripts or project setup
- Understand CLI flags or deployment options
Evidence CLI & Deployment
Level 1 — The Three Commands You Need Every Day
Create a new project
npx degit evidence-dev/template my-project
cd my-project
npm install
npm run sources
npm run dev
Start the dev server (existing project)
npm run dev
Opens at http://localhost:3000. Hot reloading is on by default — save a .md file to see changes instantly.
Build for production
npm run build
Outputs a static site to the build/ directory. All pages and queries are pre-rendered at build time.
Level 2 — All CLI Commands and Project Structure
Full Command Reference
| Command | Description |
|---|
npx degit evidence-dev/template my-project | Create a new project from the template |
npm run sources | Extract data from sources (run before first dev or build) |
npm run dev | Start the development server |
npm run build | Build the app for production |
npm run build:strict | Build, but fails on any query or component error |
npm run preview | Preview the built site locally |
Ctrl/Cmd + C | Stop the dev server |
r | Restart the dev server (while running) |
Pass flags with an extra -- separator:
npm run dev -- --port 4000
npm run dev -- --host 0.0.0.0 # useful inside containers
npm run dev -- --open /my-page # open a specific page on startup
npm run sources Flags
| Flag | Description |
|---|
--changed | Only run sources whose queries have changed |
--sources source1,source2 | Run sources from specified sources only |
--queries query1,query2 | Run specific queries only |
--debug | Show debug output |
npm run dev Flags
| Flag | Description |
|---|
--port <port> | Specify port (default 3000, auto-increments if taken) |
--host [host] | Specify hostname |
--open [path] | Open browser to path on startup |
dev and build use Vite under the hood and support Vite's CLI options. preview uses npx serve and supports Serve's options.
Project Structure
my-project/
├── pages/ # Markdown pages (.md files)
│ ├── index.md # Home page
│ └── +layout.svelte # Custom layout (optional override)
├── sources/ # Data source definitions
│ └── my_source/
│ ├── connection.yaml # Non-secret connection config
│ ├── connection.options.yaml # Secret credentials (base64)
│ └── my_query.sql # Source queries
├── static/ # Static assets (images, favicon)
├── evidence.config.yaml # Evidence configuration
└── package.json
Pages are .md files in pages/. Add a file to add a route — pages/sales/overview.md becomes /sales/overview.
Source Queries vs Markdown Queries
- Source queries (
.sql files in sources/) run directly against your data source in the source's SQL dialect. Run with npm run sources. Populate the data cache.
- Markdown queries (code blocks in
.md files) use DuckDB dialect, run against the data cache on every page load. Results are directly available to components.
Reference cached data in a markdown query as source_name.query_name:
```orders_summary
select * from my_source.my_query
```
<DataTable data={orders_summary} />
Custom Layout
Copy the default layout to override it:
cp .evidence/template/src/pages/+layout.svelte pages
Key EvidenceDefaultLayout props:
| Prop | Default | Description |
|---|
title | — | App title replacing the Evidence logo |
logo | — | Image path replacing the Evidence logo |
lightLogo / darkLogo | — | Separate logos for light/dark mode |
hideSidebar | false | Hide sidebar navigation |
hideHeader | false | Hide the page header |
hideBreadcrumbs | false | Hide breadcrumbs |
hideTOC | false | Hide table of contents |
fullWidth | false | Content spans full screen width |
maxWidth | — | Content width in pixels (default ~1280px) |
neverShowQueries | false | Remove "show queries" option in deployed app |
sidebarDepth | 3 | Sidebar nav depth (2 or 3) |
githubRepo | — | GitHub repo URL shown in header |
Level 3 — Deployment, Rendering Modes, Environments, Base Paths
Deployment Overview
Evidence is a static site generator by default. npm run build pre-renders every page and query into HTML. The output in build/ can be served from any static host.
Build process:
- All source queries run once at build time
- All pages (including all parameterized page permutations) are generated
- If a query fails during
build:strict, the build stops — the old deployed version keeps serving
Schedule or trigger regular builds to keep data fresh.
npm run build:strict fails if:
- Any SQL query fails (a query returning zero rows is not a failure)
- Any component renders an error state (a component receiving a valid but empty result set will fail — wrap with
{#if} to avoid this)
Self-Hosting Platforms
Evidence static output can be deployed to:
- AWS Amplify
- Azure Static Apps
- Cloudflare Pages
- Firebase Hosting
- GitHub Pages
- GitLab Pages
- Hugging Face Spaces
- Netlify
- Vercel
- Windows IIS
- Any static file server
Storing Credentials for Production
In production, credentials must be supplied as environment variables. They are never read from connection.options.yaml at build time on the server.
To find the exact variable names for your sources:
- Run
npm run dev
- Go to
http://localhost:3000/settings
- Open the deployment panel and select your target platform
Credential variable format:
EVIDENCE_SOURCE__<source_name>__<variable_name>
Variable names are case sensitive — preserve the casing shown on the settings page.
Environment Variables Reference
| Prefix | Usage | Example |
|---|
EVIDENCE_SOURCE__name__var | Database credentials for a named source | EVIDENCE_SOURCE__my_db__password |
EVIDENCE_VAR__name | Variables usable inside source queries | EVIDENCE_VAR__customer_name |
VITE_name | Variables accessible in .md pages via import.meta.env | VITE_tier=premium |
Using EVIDENCE_VAR__ in a source query:
select * from orders
where customer_name = '${customer_name}'
Using VITE_ in a page:
<script>
const tier = import.meta.env.VITE_tier;
</script>
{#if tier === 'premium'}
Premium content
{/if}
Evidence reads a .env file at the project root for local development.
Environments (Dev vs Prod)
Configure dev credentials via the settings page at localhost:3000/settings.
Configure prod credentials as environment variables on your deployment platform.
Common data environment patterns:
- Separate databases — same schema/tables, different database per environment
- Separate schemas — same database, different schema per environment (Postgres supports an optional
schema credential parameter)
- Separate accounts — fully isolated accounts per environment
Rendering Modes
Static Site Generation (default)
- All pages pre-rendered to HTML at build time
- Fast page loads, rich SEO
- Build time grows with page count
- Best for most apps
Single Page App (SPA)
- Only one HTML file generated; pages rendered client-side via JavaScript
- Fast builds, slower page loads, generic SEO
- Use when: >1,000 pages, very frequent data updates, or large data sources
Enabling SPA mode:
- Update
package.json scripts:
"build": "VITE_EVIDENCE_SPA=true evidence build",
"preview": "VITE_EVIDENCE_SPA=true evidence preview"
- Install the adapter:
npm install --save-dev @sveltejs/adapter-static
- Create
svelte.config.js at the project root:
import adapter from '@sveltejs/adapter-static';
export default {
kit: {
adapter: adapter({
fallback: 'index.html'
})
},
};
- When self-hosting an SPA, redirect all URLs to
index.html. NGINX example:
root /path/to/your/project/build/;
location / {
try_files $uri $uri/ $uri.html /index.html;
}
Base Paths (Subdirectory Hosting)
Serve Evidence from a subdirectory, e.g. https://acme.com/analytics.
evidence.config.yaml:
deployment:
basePath: /my-base-path
Rules:
- Must start with
/
- Must not end with
/
- Must be a valid URL path
All markdown links are automatically adjusted to include the base path.
Adjust the build output directory (required for npm run preview to work correctly):
"build": "EVIDENCE_BUILD_DIR=./build/my-base-path evidence build"
Custom Svelte components do not have links auto-adjusted. Use addBasePath:
<script>
export let link;
import { addBasePath } from '@evidence-dev/sdk/utils/svelte';
</script>
<a href={addBasePath(link)}>My Link</a>
dbt Monorepo Setup
Install Evidence inside a dbt project:
cd path/to/your/dbt/project
npx degit evidence-dev/template reports
npm --prefix ./reports install
npm --prefix ./reports run sources
npm --prefix ./reports run dev
This co-locates modelling changes (/models) and reporting changes (/reports) in the same commits.
Parallelisation
Caution — npm run dev and npm run sources write to shared cache/output directories. Do not run alongside other Evidence CLI agents on the same project.
