Quick start: Coding agents¶

npx skills add tinybirdco/tinybird-agent-skills

I'm integrating Tinybird Forward into my project. Help me set up the Typescript SDK.

Prerequisites
- Node.js 20 LTS (or newer, non-EOL)
- TypeScript >= 4.9
- Create a branch from main if not already in one

Step 1: Install the Tinybird SDK so we can run commands from anywhere

Ask for the preferred package manager. For example, if the user wants to use pnpm, run:
pnpm add -g @tinybirdco/sdk@latest

Step 2: Install the Tinybird SDK locally in the project

Install the SDK locally in the project using the package manager configured in the repository.

Step 3: Create a tinybird.config.mjs file in the root of the repository
/** @type {import("@tinybirdco/sdk").TinybirdConfig} */
const tinybirdConfig = {
  include: ["/lib/tinybird.ts"],
  token: process.env.TINYBIRD_TOKEN,
  baseUrl: process.env.TINYBIRD_URL,
  devMode: "branch", // or "local" if you want to run the project locally (Tinybird Local required)
};

export default tinybirdConfig;

Step 4: Create .env.local file
TINYBIRD_TOKEN=xxxxxxx
TINYBIRD_URL=xxxxxxx

Step 5: Create lib/tinybird.ts
/**
 * Tinybird Definitions
 *
 * Define your datasources, endpoints, and client here.
 */

import {
  defineDatasource,
  defineEndpoint,
  Tinybird,
  node,
  t,
  p,
  engine,
  type InferRow,
  type InferParams,
  type InferOutputRow,
} from "@tinybirdco/sdk";

// ============================================================================
// Datasources
// ============================================================================

/**
 * Page views datasource - tracks page view events
 */
export const pageViews = defineDatasource("page_views", {
  description: "Page view tracking data",
  schema: {
    timestamp: t.dateTime(),
    session_id: t.string(),
    pathname: t.string(),
    referrer: t.string().nullable(),
  },
  engine: engine.mergeTree({
    sortingKey: ["pathname", "timestamp"],
  }),
});

export type PageViewsRow = InferRow<typeof pageViews>;

// ============================================================================
// Endpoints
// ============================================================================

/**
 * Top pages endpoint - get the most visited pages
 */
export const topPages = defineEndpoint("top_pages", {
  description: "Get the most visited pages",
  params: {
    start_date: p.dateTime().describe("Start of date range"),
    end_date: p.dateTime().describe("End of date range"),
    limit: p.int32().optional(10).describe("Number of results"),
  },
  nodes: [
    node({
      name: "aggregated",
      sql: `
        SELECT
          pathname,
          count() AS views
        FROM page_views
        WHERE timestamp >= {{DateTime(start_date)}}
          AND timestamp <= {{DateTime(end_date)}}
        GROUP BY pathname
        ORDER BY views DESC
        LIMIT {{Int32(limit, 10)}}
      `,
    }),
  ],
  output: {
    pathname: t.string(),
    views: t.uint64(),
  },
});

export type TopPagesParams = InferParams<typeof topPages>;
export type TopPagesOutput = InferOutputRow<typeof topPages>;

// ============================================================================
// Client
// ============================================================================

export const tinybird = new Tinybird({
  datasources: { pageViews },
  pipes: { topPages },
});

Step 6: Setup is completed.

Ask the user to replace the TINYBIRD_* environment variables with the actual values from the quickstart and show the next steps to run:

# Build project
tinybird build

// Ingest data into the data source
await tinybird.pageViews.ingest({
  timestamp: new Date(),
  pathname: '/',
  session_id: '1234567890',
  country: 'US',
});

// Fetch the endpoint data
const result = await tinybird.topPages({
  start_date: new Date('2024-01-01'),
  end_date: new Date('2024-01-02'),
  limit: 10,
});

If some issue appears, check the README.md in the @tinybirdco/sdk repository for more information: https://github.com/tinybirdco/tinybird-sdk-typescript

I'm integrating Tinybird Forward into my project. Help me set up the Tinybird CLI workflow using datafiles.

Prerequisites
- Tinybird account available
- Git available

Step 1: Install the Tinybird CLI

Run the official install script:
    curl https://tinybird.co | sh

On Windows, run:
    powershell -ExecutionPolicy ByPass -c "irm https://tinybird.co | iex"

Step 2: Initialize project

Run:
    tb init

When prompted, use type=cli and dev mode=branch.

Step 3: Initialize git and branch

If repository is not initialized:
    git init

Create or switch to a feature branch:
    git checkout -b tinybird_intro

Step 4: Create base data source

Use the NYC taxi dataset to create `trips`.
    tb --cloud datasource create --url https://tbrd.co/taxi_data.parquet --name trips

Step 5: Create lookup data source
    tb --cloud datasource create --url https://d37ci6vzurychx.cloudfront.net/misc/taxi_zone_lookup.csv --name taxi_zone_lookup

Step 6: Create endpoint file

Create `endpoints/best_tip_zones.pipe` with:

TOKEN best_tips_read READ

DESCRIPTION >
    Endpoint that finds the zone most likely to have better tips for a given pickup location

NODE pickup_zone_lookup
SQL >
    %
    SELECT locationid
    FROM taxi_zone_lookup
    WHERE zone ILIKE concat('%', {{String(pickup_zone, 'JFK Airport')}}, '%')
    LIMIT 1

NODE tip_analysis
SQL >
    %
    SELECT
        t.DOLocationID,
        tz.zone as destination_zone,
        avg(t.tip_amount) as avg_tip,
        count(*) as trip_count,
        avg(t.tip_amount / nullif(t.total_amount, 0)) as tip_percentage
    FROM trips t
    LEFT JOIN taxi_zone_lookup tz ON t.DOLocationID = tz.locationid
    WHERE t.PULocationID = (SELECT locationid FROM pickup_zone_lookup)
      AND t.tip_amount > 0
      AND t.total_amount > 0
    GROUP BY t.DOLocationID, tz.zone
    HAVING trip_count >= 10
    ORDER BY avg_tip DESC
    LIMIT 10

TYPE endpoint

Step 7: Build

Run:
    tb build

Step 8: Load sample data

Use current git branch as BRANCH_NAME (for example tinybird_intro).
    tb --branch=$BRANCH_NAME datasource append trips --url https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2025-05.parquet
    tb --branch=$BRANCH_NAME datasource append taxi_zone_lookup --url https://d37ci6vzurychx.cloudfront.net/misc/taxi_zone_lookup.csv

Step 9: Test endpoint

    tb --branch=$BRANCH_NAME token copy "best_tips_read"
    TB_BRANCH_TOKEN=$(pbpaste)
    TB_BRANCH_HOST=$(cat .tinyb | jq -r ".host")
    curl -X GET "$TB_BRANCH_HOST/v0/pipes/best_tip_zones.json?token=$TB_BRANCH_TOKEN&pickup_zone=Newark+Airport"

Step 10: Deploy to Tinybird Cloud workspace

Run:
    tb deploy

Show the next steps:
    tb --cloud datasource append trips --url https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2025-05.parquet
    tb --cloud datasource append taxi_zone_lookup --url https://d37ci6vzurychx.cloudfront.net/misc/taxi_zone_lookup.csv
    tb --cloud open

If some issue appears, check the CLI reference: https://www.tinybird.co/docs/forward/dev-reference/commands