@valerypopoff/rivet2-cli 2.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Val P.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @valerypopoff/rivet2-cli
+
+Command-line tools for running and serving Rivet 2.0 projects through the Node runtime.
+
+## Usage
+
+```bash
+npx @valerypopoff/rivet2-cli --help
+npx @valerypopoff/rivet2-cli run my-project.rivet-project
+npx @valerypopoff/rivet2-cli serve my-project.rivet-project --port 8080
+```
+
+The CLI package exposes the `rivet` binary when installed globally:
+
+```bash
+npm install -g @valerypopoff/rivet2-cli
+rivet --help
+```
+
+## Development
+
+```bash
+yarn workspace @valerypopoff/rivet2-cli run build
+yarn workspace @valerypopoff/rivet2-cli run test
+yarn workspace @valerypopoff/rivet2-cli run lint
+```
+
+See the root [README](../../README.md), [package docs](../../developer-docs/PACKAGES.md), and public CLI docs under [packages/docs/docs/cli.md](../docs/docs/cli.md).

package/bin/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { makeCommand as makeRunCommand, run } from './commands/run.js';
+import { makeCommand as makeServeCommand, serve } from './commands/serve.js';
+await yargs(hideBin(process.argv))
+    .command('run <projectFile> [graphName]', 'Run a graph in a project file, or the main graph if graphName is not specified.', (y) => makeRunCommand(y), (args) => run(args))
+    .command('serve [projectFile]', 'Serve a project file as a REST API.', (y) => makeServeCommand(y), (args) => serve(args))
+    .demandCommand()
+    .parseAsync();

package/bin/commands/run.js

@@ -0,0 +1,98 @@
+import { createProcessor, loadProjectFromFile } from '@valerypopoff/rivet2-node';
+import { resolve } from 'node:path';
+export function makeCommand(y) {
+    return y
+        .positional('projectFile', {
+        describe: 'The project file to run',
+        type: 'string',
+        demandOption: true,
+    })
+        .positional('graphName', {
+        describe: 'The name of the graph to run',
+        type: 'string',
+    })
+        .option('inputs-stdin', {
+        describe: 'Read inputs from stdin as JSON',
+        type: 'boolean',
+        default: false,
+    })
+        .option('include-cost', {
+        describe: 'Include the total cost in the output',
+        type: 'boolean',
+        default: false,
+    })
+        .option('context', {
+        describe: 'Adds a context value to the graph run',
+        type: 'string',
+        array: true,
+        default: [],
+    })
+        .option('input', {
+        describe: 'Adds an input to the graph run',
+        type: 'string',
+        array: true,
+        default: [],
+    });
+}
+export async function run(args) {
+    try {
+        const projectPath = resolve(process.cwd(), args.projectFile);
+        const project = await loadProjectFromFile(projectPath);
+        if (!args.graphName && !project.metadata.mainGraphId) {
+            const validGraphs = Object.values(project.graphs).map((graph) => [graph.metadata.id, graph.metadata.name]);
+            const validGraphNames = validGraphs.map(([id, name]) => `• "${name}" (${id})`);
+            console.error(`No graph name provided, and project does not specify a main graph. Valid graphs are: \n${validGraphNames.join('\n')}\n\n Use either the graph's name or its ID. For example, \`rivet run my-project.rivet-project my-graph\` or \`rivet run my-project.rivet-project 1234abcd\``);
+            process.exit(1);
+        }
+        let inputs = {};
+        if (args.inputsStdin) {
+            // Read json from stdin
+            const stdin = process.stdin;
+            stdin.setEncoding('utf8');
+            let input = '';
+            for await (const chunk of stdin) {
+                input += chunk;
+            }
+            try {
+                inputs = JSON.parse(input);
+            }
+            catch (err) {
+                console.error('Failed to parse input JSON');
+                console.error(err);
+                process.exit(1);
+            }
+        }
+        else {
+            inputs = Object.fromEntries(args.input.map((input) => {
+                const [key, value] = input.split('=');
+                if (!key || !value) {
+                    console.error(`Invalid input value: ${input}`);
+                    process.exit(1);
+                }
+                return [key, value];
+            }));
+        }
+        const contextValues = Object.fromEntries(args.context.map((context) => {
+            const [key, value] = context.split('=');
+            if (!key || !value) {
+                console.error(`Invalid context value: ${context}`);
+                process.exit(1);
+            }
+            return [key, value];
+        }));
+        const { run } = createProcessor(project, {
+            graph: args.graphName,
+            inputs,
+            context: contextValues,
+        });
+        const outputs = await run();
+        if (!args.includeCost) {
+            delete outputs.cost;
+        }
+        console.log(JSON.stringify(outputs, null, 2));
+    }
+    catch (err) {
+        console.error(err);
+        process.exit(1);
+    }
+}

package/bin/commands/serve.js

@@ -0,0 +1,271 @@
+import { Hono } from 'hono';
+import { serve as serveHono } from '@hono/node-server';
+import { readdir, stat } from 'node:fs/promises';
+import { extname, isAbsolute, join } from 'node:path';
+import didYouMean from 'didyoumean2';
+import { createProcessor, loadProjectFromFile, getSingleNodeStream, } from '@valerypopoff/rivet2-node';
+import chalk from 'chalk';
+import { configDotenv } from 'dotenv';
+export function makeCommand(y) {
+    return y
+        .option('port', {
+        describe: 'The port to serve on',
+        type: 'number',
+        default: 3000,
+    })
+        .option('dev', {
+        describe: 'Run in development mode: rereads the project file on each request',
+        type: 'boolean',
+        default: false,
+    })
+        .option('graph', {
+        describe: 'The ID or name of the graph to run. If omitted, the main graph is used.',
+        type: 'string',
+        demandOption: false,
+    })
+        .option('allow-specifying-graph-id', {
+        describe: 'Allow specifying the graph ID in the URL path',
+        type: 'boolean',
+        default: false,
+    })
+        .option('openai-api-key', {
+        describe: 'The OpenAI API key to use for the project. If omitted, the environment variable OPENAI_API_KEY is used.',
+        type: 'string',
+        demandOption: false,
+    })
+        .option('openai-endpoint', {
+        describe: 'The OpenAI API endpoint to use for the project. If omitted, the environment variable OPENAI_ENDPOINT is used.',
+        type: 'string',
+        demandOption: false,
+    })
+        .option('openai-organization', {
+        describe: 'The OpenAI organization to use for the project. If omitted, the environment variable OPENAI_ORGANIZATION is used.',
+        type: 'string',
+        demandOption: false,
+    })
+        .option('expose-cost', {
+        describe: 'Expose the cost of the graph run in the response',
+        type: 'boolean',
+        default: false,
+    })
+        .option('stream', {
+        describe: 'Turns on streaming mode. Rivet events will be sent to the client using SSE (Server-Sent Events). If this is set to a Node ID or node title, only events for that node will be sent.',
+        type: 'string',
+        demandOption: false,
+    })
+        .option('stream-node', {
+        describe: 'Streams the partial outputs of a specific node. Requires --stream to be set.',
+        type: 'string',
+        demandOption: false,
+    })
+        .positional('projectFile', {
+        describe: 'The project file to serve. If omitted, the project file in the current directory is used. There cannot be multiple project files in the current directory.',
+        type: 'string',
+        demandOption: false,
+    });
+}
+export async function serve(args) {
+    try {
+        configDotenv();
+        const app = new Hono();
+        const projectFilePath = await getProjectFile(args.projectFile);
+        const initialProject = await loadProjectFromFile(projectFilePath);
+        throwIfNoMainGraph(initialProject, args.graph, projectFilePath);
+        throwIfInvalidGraph(initialProject, args.graph);
+        if (args.stream != null) {
+            console.log('Streaming is enabled');
+        }
+        if (args.streamNode != null) {
+            console.log(`Streaming node ${chalk.bold(args.streamNode)}`);
+        }
+        app.post('/', async (c) => {
+            const project = args.dev ? await loadProjectFromFile(projectFilePath) : initialProject;
+            const text = await c.req.text();
+            let inputs = {};
+            if (text.trim()) {
+                inputs = JSON.parse(text);
+                if (typeof inputs !== 'object') {
+                    throw new Error('Inputs must be an object');
+                }
+            }
+            if (args.stream != null) {
+                const stream = await streamGraph({ project, inputs, graphId: args.graph, ...args });
+                return new Response(stream, {
+                    headers: {
+                        'Content-Type': 'text/event-stream',
+                        'Cache-Control': 'no-cache',
+                        Connection: 'keep-alive',
+                    },
+                });
+            }
+            else {
+                const outputs = await runGraph({ project, inputs, graphId: args.graph, ...args });
+                return c.json(outputs);
+            }
+        });
+        if (args.allowSpecifyingGraphId) {
+            app.post('/:graphId', async (c) => {
+                const project = args.dev ? await loadProjectFromFile(projectFilePath) : initialProject;
+                const inputs = await c.req.json();
+                const graphId = c.req.param('graphId');
+                const outputs = await runGraph({ project, inputs, graphId, ...args });
+                return c.json(outputs);
+            });
+        }
+        const server = serveHono({
+            port: args.port,
+            fetch: app.fetch,
+        });
+        let servedGraphName;
+        if (args.graph) {
+            const graph = Object.values(initialProject.graphs).find((g) => g.metadata.id === args.graph || g.metadata.name === args.graph);
+            servedGraphName = graph.metadata.name;
+        }
+        else {
+            const graph = Object.values(initialProject.graphs).find((g) => g.metadata.id === initialProject.metadata.mainGraphId);
+            servedGraphName = graph.metadata.name;
+        }
+        console.log(`${chalk.green(`Serving project file ${chalk.bold.white(projectFilePath)} on port ${chalk.bold.white(args.port)}.\nServing graph "${chalk.bold.white(servedGraphName)}".`)}`);
+        function shutdown() {
+            console.log('Shutting down...');
+            server.close((err) => {
+                if (err) {
+                    console.error(err);
+                    process.exit(1);
+                }
+                process.exit(0);
+            });
+        }
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    }
+    catch (err) {
+        console.error(chalk.red(err));
+        process.exit(1);
+    }
+}
+async function streamGraph({ project, inputs, graphId, openaiApiKey, openaiEndpoint, openaiOrganization, streamNode, }) {
+    const { run, processor, getSSEStream } = createProcessor(project, {
+        inputs,
+        graph: graphId,
+        openAiKey: openaiApiKey,
+        openAiEndpoint: openaiEndpoint,
+        openAiOrganization: openaiOrganization,
+    });
+    if (streamNode) {
+        const stream = getSingleNodeStream(processor, streamNode);
+        run().catch((err) => {
+            console.error(err);
+        });
+        return stream;
+    }
+    else {
+        const stream = getSSEStream({
+            nodeStart: streamNode ? [streamNode] : true,
+            nodeFinish: streamNode ? [streamNode] : true,
+            partialOutputs: streamNode ? [streamNode] : true,
+        });
+        run().catch((err) => {
+            console.error(err);
+        });
+        return stream;
+    }
+}
+async function runGraph({ project, inputs, graphId, openaiApiKey, openaiEndpoint, openaiOrganization, exposeCost, }) {
+    const { run } = createProcessor(project, {
+        inputs,
+        graph: graphId,
+        openAiKey: openaiApiKey,
+        openAiEndpoint: openaiEndpoint,
+        openAiOrganization: openaiOrganization,
+    });
+    const outputs = await run();
+    if (!exposeCost) {
+        delete outputs.cost;
+    }
+    return outputs;
+}
+function throwIfNoMainGraph(project, graph, projectFilePath) {
+    if (!project.metadata.mainGraphId && !graph) {
+        const validGraphs = Object.values(project.graphs).map((graph) => [graph.metadata.id, graph.metadata.name]);
+        if (validGraphs.length === 0) {
+            throw new Error('No graphs found in the project file. Please edit the project file in Rivet and add a graph.');
+        }
+        const validGraphNames = validGraphs.map(([id, name]) => `• "${name}" (${id})`);
+        const firstExample = `rivet serve ${projectFilePath} --graph ${validGraphs[0][0]}`;
+        const secondExample = `rivet serve ${projectFilePath} --graph "${validGraphs[0][1]}"`;
+        throw new Error(`No graph name provided, and project does not specify a main graph. Valid graphs are: \n\n${validGraphNames.join('\n')}\n\n Use either the graph's name or its ID. For example, \n• \`${chalk.bold(firstExample)}\` or\n• \`${chalk.bold(secondExample)}\``);
+    }
+}
+function throwIfInvalidGraph(project, graph) {
+    if (project.metadata.mainGraphId && !graph) {
+        return;
+    }
+    const matchingGraph = Object.values(project.graphs).find((g) => g.metadata.id === graph || g.metadata.name === graph);
+    if (!matchingGraph) {
+        const validGraphsAndIds = Object.values(project.graphs).flatMap((graph) => [
+            graph.metadata.id,
+            graph.metadata.name,
+        ]);
+        const suggestion = didYouMean(graph, validGraphsAndIds);
+        if (suggestion) {
+            throw new Error(`Graph "${graph}" not found in project file. Did you mean \`${chalk.bold(`--graph "${suggestion}"`)}\`?`);
+        }
+        else {
+            const validGraphsAndIds = Object.values(project.graphs)
+                .map((graph) => `• "${graph.metadata.name}" (${graph.metadata.id})`)
+                .join('\n');
+            throw new Error(`Graph "${graph}" not found in project file. Valid graphs are: \n${validGraphsAndIds}`);
+        }
+    }
+}
+async function getProjectFile(initialProjectFilePath) {
+    let projectFilePath = initialProjectFilePath ?? (await getProjectFilePathFromDirectory(process.cwd()));
+    await throwIfMissingFile(projectFilePath);
+    if ((await stat(projectFilePath)).isDirectory()) {
+        projectFilePath = await getProjectFilePathFromDirectory(projectFilePath);
+    }
+    return projectFilePath;
+}
+async function getProjectFilePathFromDirectory(directory) {
+    const files = await readdir(directory);
+    const projectFiles = files.filter((file) => extname(file) === '.rivet-project');
+    if (projectFiles.length === 0) {
+        throw new Error('No project file found in the current directory. Project files should end with .rivet-project.');
+    }
+    if (projectFiles.length > 1) {
+        throw new Error(`Multiple project files found in the current directory. Please specify which one to serve: \n${projectFiles.join('\n')}`);
+    }
+    return join(directory, projectFiles[0]);
+}
+async function throwIfMissingFile(filePath) {
+    try {
+        await stat(filePath);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+        if (isAbsolute(filePath)) {
+            const parentDir = filePath.split('/').slice(0, -1).join('/');
+            const possibleFiles = await readdir(parentDir);
+            const suggestion = didYouMean(filePath, possibleFiles);
+            if (suggestion) {
+                throw new Error(`Could not find project file "${filePath}". Did you mean "${suggestion}"?`);
+            }
+            else {
+                throw new Error(`Could not find project file "${filePath}".`);
+            }
+        }
+        else {
+            const possibleFiles = await readdir(process.cwd());
+            const suggestion = didYouMean(filePath, possibleFiles);
+            if (suggestion) {
+                throw new Error(`Could not find project file "${filePath}". Did you mean "${suggestion}"?`);
+            }
+            else {
+                throw new Error(`Could not find project file "${filePath}".`);
+            }
+        }
+    }
+}

package/dist/types/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/commands/run.d.ts

@@ -0,0 +1,22 @@
+import type * as yargs from 'yargs';
+export declare function makeCommand<T>(y: yargs.Argv<T>): yargs.Argv<T & {
+    projectFile: string;
+} & {
+    graphName: string | undefined;
+} & {
+    "inputs-stdin": boolean;
+} & {
+    "include-cost": boolean;
+} & {
+    context: never[] | string[];
+} & {
+    input: never[] | string[];
+}>;
+export declare function run(args: {
+    projectFile: string;
+    graphName: string | undefined;
+    inputsStdin: boolean;
+    includeCost: boolean;
+    context: string[];
+    input: string[];
+}): Promise<void>;

package/dist/types/commands/serve.d.ts

@@ -0,0 +1,37 @@
+import type * as yargs from 'yargs';
+export declare function makeCommand<T>(y: yargs.Argv<T>): yargs.Argv<T & {
+    port: number;
+} & {
+    dev: boolean;
+} & {
+    graph: string | undefined;
+} & {
+    "allow-specifying-graph-id": boolean;
+} & {
+    "openai-api-key": string | undefined;
+} & {
+    "openai-endpoint": string | undefined;
+} & {
+    "openai-organization": string | undefined;
+} & {
+    "expose-cost": boolean;
+} & {
+    stream: string | undefined;
+} & {
+    "stream-node": string | undefined;
+} & {
+    projectFile: string | undefined;
+}>;
+export declare function serve(args: {
+    port: number;
+    projectFile: string | undefined;
+    dev: boolean;
+    graph: string | undefined;
+    allowSpecifyingGraphId: boolean;
+    openaiApiKey: string | undefined;
+    openaiEndpoint: string | undefined;
+    openaiOrganization: string | undefined;
+    exposeCost: boolean;
+    stream: string | undefined;
+    streamNode: string | undefined;
+}): Promise<void>;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@valerypopoff/rivet2-cli",
+  "version": "2.0.0",
+  "license": "MIT",
+  "types": "dist/types/cli.d.ts",
+  "type": "module",
+  "bin": {
+    "rivet": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/valerypopoff/rivet2.0.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.8",
+    "@types/dotenv": "^8.2.3",
+    "@valerypopoff/rivet2-node": "^2.0.0",
+    "chalk": "^5.4.1",
+    "didyoumean2": "^7.0.4",
+    "dotenv": "^16.4.7",
+    "hono": "^4.7.0",
+    "yargs": "^17.7.2"
+  }
+}