msgbyte--tianji/packages/cli

Tianji CLI

Command-line tool for developing and deploying Tianji Workers.

Installation

From Source (Development)

# In the Tianji monorepo root
pnpm install
cd packages/cli
pnpm build

# Link globally for development
pnpm link --global

From NPM (When Published)

npm install -g tianji-cli
# or
pnpm add -g tianji-cli

Usage

Login to Tianji

Before deploying workers, you need to login to your Tianji instance:

tianji login

You will be prompted for:

• Server URL: Your Tianji server URL (e.g., https://tianji.example.com)
• Workspace ID: Your workspace ID (found in Tianji dashboard)
• API Key: Your API key (generate from Tianji settings)

The credentials are saved to ~/.config/tianji/config.json.

Create a New Worker Project

# Create in a new directory
tianji worker init my-worker

# Or initialize in current directory
mkdir my-worker && cd my-worker
tianji worker init

This creates a new project with:

• src/index.ts: Worker handler function
• vite.config.ts: Build configuration
• package.json: Dependencies
• .tianjirc: Project configuration

Develop Your Worker

Edit src/index.ts to implement your worker logic:

export default async function handler(payload: any, context: any) {
  // Your worker logic here
  return {
    success: true,
    message: 'Hello from Tianji Worker!',
    data: payload,
  };
}

Build and Deploy

# Login first (if not already logged in)
tianji login

# Install dependencies (first time only)
npm install

# Build the worker
npm run build

# Deploy to Tianji
tianji worker deploy

The worker will be built using Vite and deployed to your Tianji instance. After deployment, you'll receive a URL to access your worker.

Project Structure

my-worker/
├── src/
│   └── index.ts          # Worker entry point
├── dist/                 # Built output (generated)
├── package.json          # Project dependencies
├── vite.config.ts        # Vite build configuration
├── tsconfig.json         # TypeScript configuration
├── .tianjirc             # Tianji project config
└── README.md             # Project documentation

Worker API

Your worker receives two parameters:

payload

The request payload containing query parameters and request body merged together.

context

The request context with the following structure:

interface RequestContext {
  type: 'http' | 'cron';
  request?: {
    method: string;
    url: string;
    headers: Record<string, string>;
  };
}

• For HTTP requests: context.type === 'http' and context.request contains request details
• For cron-triggered workers: context.type === 'cron'

Configuration Files

.tianjirc

Project-level configuration stored in your worker project:

{
  "name": "my-worker",
  "workerId": "clxxx..." // Auto-generated after first deployment
}

~/.config/tianji/config.json

Global configuration for CLI authentication:

{
  "serverUrl": "https://tianji.example.com",
  "workspaceId": "clxxx...",
  "apiKey": "your-api-key"
}

Commands

tianji login

Login to Tianji and save credentials.

tianji worker init [project-name]

Create a new Tianji Worker project.

Options:

• project-name: Optional. Name of the project directory to create.

tianji worker deploy

Build and deploy the current worker project to Tianji.

Must be run from a worker project directory (containing .tianjirc).

Examples

Simple Echo Worker

export default async function handler(payload: any) {
  return {
    echo: payload,
    timestamp: new Date().toISOString(),
  };
}

HTTP Method-Based Worker

export default async function handler(payload: any, context: any) {
  if (context.type !== 'http') {
    return { error: 'Only HTTP requests supported' };
  }

  const method = context.request?.method;
  
  switch (method) {
    case 'GET':
      return { message: 'Hello GET' };
    case 'POST':
      return { message: 'Data received', data: payload };
    default:
      return { error: 'Method not supported' };
  }
}

Cron Worker

export default async function handler(payload: any, context: any) {
  if (context.type === 'cron') {
    // Perform scheduled task
    console.log('Cron job executed at:', new Date().toISOString());
    return { success: true };
  }
  
  return { error: 'This worker only runs on schedule' };
}

Troubleshooting

"Not logged in" Error

Run tianji login to authenticate.

".tianjirc not found" Error

Make sure you're in a worker project directory. Run tianji worker init to create a new project.

"Build failed" Error

Ensure all dependencies are installed:

npm install

Check that your src/index.ts has a default export function.

"Deployment failed" Error

• Verify your credentials are correct (try logging in again)
• Check that your API key has the necessary permissions
• Ensure your server URL is accessible

Learn More

• Tianji Documentation
• Worker Documentation

License

MIT