Opik TS - Interactive Setup Tool

The Opik TS is an interactive command-line tool that streamlines the process of adding Opik observability to your Node.js and TypeScript applications. It automatically detects your project setup, installs dependencies, and configures tracing for your LLM integrations.

Features

• 🔍 Smart Detection: Automatically detects your project setup (package manager, TypeScript configuration, existing integrations)
• 📦 Package Management: Supports npm, yarn, pnpm, and bun
• ⚙️ Environment Configuration: Creates or updates .env files with proper Opik configuration

Getting Started

Basic Usage

Run the CLI in your project directory:

$
npx opik-ts configure

The CLI will guide you through:

1. Project Detection: Identifies your package manager and project structure
2. Dependency Installation: Installs Opik SDK and integration packages
3. Environment Setup: Configures API keys and environment variables
4. Code Generation: Sets up Opik client in your root project folder
5. Formatting: Optionally applies Prettier formatting

Requirements

• Node.js: Version 18.17.0 or higher
• Package Manager: npm, yarn, pnpm, or bun
• Supported Project Types:
  • Node.js applications
  • TypeScript projects
  • Express/Fastify APIs

CLI Options

The CLI supports several command-line options for customization:

Examples

Verbose debugging mode:

$
npx opik-ts configure --debug

Non-interactive mode with defaults:

$
npx opik-ts configure --default

Install in a specific directory:

$
npx opik-ts configure --install-dir=./my-app

Force installation (skip peer dependency checks):

$
npx opik-ts configure --force-install

Local development setup:

$
npx opik-ts configure --use-local

This will skip the deployment selection step and automatically configure your environment for local development (localhost:5173).

Environment Configuration

The CLI automatically creates or updates your .env file with the necessary configuration:

$
# Opik Configuration
$
OPIK_API_KEY=your-api-key-here
$
OPIK_URL_OVERRIDE=https://www.comet.com/opik/api
$
OPIK_PROJECT_NAME=default
$
OPIK_WORKSPACE=default

Troubleshooting

Permission Errors

If you encounter permission errors during installation:

$
# Use --force-install to bypass peer dependency checks
$
npx opik-ts configure --force-install

Package Manager Issues

If the CLI fails to detect your package manager:

1. Ensure you have a package.json in your project directory
2. Try running the CLI with debug mode: npx opik-ts configure --debug
3. Manually specify your package manager by selecting it from the prompts

Environment Variable Setup

If environment variables aren’t being set correctly:

1. Check that .env file was created in your project root
2. Ensure your application loads environment variables (e.g., using dotenv)
3. Restart your development server after running the CLI

Integration Not Working

If traces aren’t appearing in Opik:

1. Verify your OPIK_API_KEY is correct
2. Check that OPIK_URL_OVERRIDE points to the right endpoint
3. Ensure you’re calling flush() before your application exits:

   1
   await trackedClient.flush();

Debug Mode

Enable verbose logging to troubleshoot issues:

$
npx opik-ts configure --debug

This will show detailed information about:

• Project detection results
• Package installation steps
• File modifications
• Configuration changes

CI/CD Integration

For automated deployments, use the non-interactive mode:

$
# In your CI/CD pipeline
$
npx opik-ts configure --default --force-install

Set environment variables beforehand:

$
export OPIK_API_KEY="your-api-key"
$
export OPENAI_API_KEY="your-openai-key"
$
npx opik-ts configure --default

Next Steps

After running the CLI:

1. Start Your Application: Run your application and make LLM calls to see traces in Opik
2. Explore Traces: Visit the Opik dashboard to view your traces
3. Add Custom Spans: Learn about manual tracing for custom instrumentation
4. Set Up Evaluation: Configure evaluation metrics for your LLM outputs
5. Production Monitoring: Set up production monitoring for your application

Further Resources

• TypeScript SDK Overview
• OpenAI TypeScript Integration
• LangChain TypeScript Integration
• Vercel AI SDK Integration
• GitHub Repository