Skip to content
Skills Library
Data & analytics · Building & coding

evidence-cli

/evidence-cli

Use when running Evidence.dev CLI commands, configuring projects or deploying — dev server, build, rendering modes, environment variables and deployment platforms.

Licence
MIT
Last repository change
02.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
5
Deprecation

No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when running Evidence.dev CLI commands, configuring projects or deploying — dev server, build, rendering modes, environment variables and deployment platforms.

Original author description

Use when running Evidence.dev CLI commands, configuring projects or deploying — dev server, build, rendering modes, environment variables and deployment platforms.

How it works

  1. When to use
  2. Level 1 — The Three Commands You Need Every Day
  3. Level 2 — All CLI Commands and Project Structure
  4. Level 3 — Deployment, Rendering Modes, Environments, Base Paths
  5. Parallelisation
Original SKILL.md headings · 338 lines, 1,451 words
SKILL.md preview
---
name: evidence-cli
description: Use when running Evidence.dev CLI commands, configuring projects or deploying — dev server, build, rendering modes, environment variables and 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

```shell
npx degit evidence-dev/template my-project
cd my-project
npm install
npm run sources
npm run dev
```

### Start the dev server (existing project)

```shell
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

```shell
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:

```shell
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](https://vitejs.dev/guide/cli.html#options). `preview` uses `npx serve` and supports [Serve's options](https://github.com/vercel/serve/blob/main/source/utilities/cli.ts#L30).

### 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`:

````markdown
```orders_summary
select * from my_source.my_query
```

<DataTable data={orders_summary} />
````

### Custom Layout

Copy the default layout to override it:

```bash
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:
1. All source queries run once at build time
2. All pages (including all parameterized page permutations) are generated
3. 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:
1. Run `npm run dev`
2. Go to `http://localhost:3000/settings`
3. 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:**

```sql
select * from orders
where customer_name = '${customer_name}'
```

**Using `VITE_` in a page:**

```svelte
<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:**

1. Update `package.json` scripts:

```json
"build": "VITE_EVIDENCE_SPA=true evidence build",
"preview": "VITE_EVIDENCE_SPA=true evidence preview"
```

2. Install the adapter:

```bash
npm install --save-dev @sveltejs/adapter-static
```

3. Create `svelte.config.js` at the project root:

```javascript
import adapter from '@sveltejs/adapter-static';

export default {
    kit: {
        adapter: adapter({
            fallback: 'index.html'
        })
    },
};
```

4. When self-hosting an SPA, redirect all URLs to `index.html`. NGINX example:

```nginx
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://example.com/analytics`.

**`evidence.config.yaml`:**

```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):

```json
"build": "EVIDENCE_BUILD_DIR=./build/my-base-path evidence build"
```

**Custom Svelte components** do not have links auto-adjusted. Use `addBasePath`:

```svelte
<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:

```shell
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.

Versions

The database has no other skills named evidence-cli.

Database snapshot: 13.11.2026 · package version 068c35c22b95 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100local-dev
    Local development environment setup and commands. Use when helping with dev server, Docker, or local testing.
  • 95sapui5-cli
    Manages SAPUI5/OpenUI5 projects using the UI5 Tooling CLI (@ui5/cli). Use when initializing UI5 projects, configuring ui5.yaml or ui5-workspace.yaml files, building UI5 applications or libraries, running development servers with HTTP/2 support, creating custom build tasks or…
  • 95sapui5-cli
    Manages SAPUI5/OpenUI5 projects using the UI5 Tooling CLI (@ui5/cli). Use when initializing UI5 projects, configuring ui5.yaml or ui5-workspace.yaml files, building UI5 applications or libraries, running development servers with HTTP/2 support, creating custom build tasks or…
  • 100evidence-custom
    Use when creating Evidence.dev custom components or plugins — building Svelte components, component queries, plugin development and publishing.
  • 100cf-cli
    Cloudflare's official cf CLI (beta) for the public Cloudflare API and Workers projects. Use for finding and running Cloudflare commands from the terminal — sign-in and profiles, cf cli search, cf schema, cf deploy/dev/build, resource commands for DNS, zones, D1, KV, and R2 — and…
  • 100hyperframes-cli
    HyperFrames CLI dev loop \u2014 `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.