lovart

Node.js CLI wrapper for the local Lovart HTTP service. This package does not implement generation itself; it turns command-line options into requests to the service exposed by this repository.

By default the CLI talks to:

http://127.0.0.1:3030

Start the service from the repository root before submitting real jobs:

npm run lovart:serve

Install

Run without installing:

npx -y lovart@latest --help

Or install once:

npm install -g lovart

Install The Agent Skill

The npm package includes the Lovart agent skill and its bundled references.

Install globally for Codex:

npx -y lovart@latest skill init --ai codex --global

Or, after installing the CLI globally:

lovart skill init --ai codex --global

Install into the current project:

lovart skill init --ai codex

Use --force to overwrite an existing skill directory.

Install from Source

cd cli
npm install
npm link

Or run directly from this directory:

npx . --help

Configuration

Persistent auth is stored in ~/.config/lovart/config.json.

lovart auth login
lovart auth status
lovart auth logout

You can also save a token non-interactively:

lovart auth login --token "$LOVART_API_TOKEN" --base-url http://127.0.0.1:3030

Environment variables override saved configuration:

• LOVART_API_BASE_URL
• LOVART_API_PROTOCOL
• LOVART_API_HOST
• LOVART_API_PORT
• LOVART_API_TOKEN
• LOVART_PROJECT_ID

Local file upload helpers use provider-specific upload settings cached by lovart auth login. The CLI does not ship access keys or COS credentials, and normal users do not need to configure them locally.

Configure upload settings once in the Lovart service Web admin console. During lovart auth login, the CLI fetches those settings from the authenticated service and stores them in ~/.config/lovart/config.json.

The service-side Web admin form stores these values for generator reference uploads, such as image2image, frames2video, multiref2video, and videoedit:

• LOVART_ACCESS_KEY
• LOVART_SECRET_KEY
• LOVART_UPLOAD_BASE_URL optional, defaults to https://lgw.lovart.ai
• LOVART_UPLOAD_PATH optional, defaults to /v1/openapi/file/upload

The service-side Web admin form stores these values for moderated asset uploads with asset_upload and a local --source path:

• COS_SECRET_ID
• COS_SECRET_KEY
• COS_BUCKET
• COS_REGION
• COS_BASE_URL optional, defaults to the COS bucket host
• COS_PATH_PREFIX optional, defaults to lovart-uploads

For RunningHub background removal:

• RUNNINGHUB_API_KEY

Command Shape

lovart [--json] [--raw] <command> [options]

Use the built-in help as the source of truth for flags:

lovart --help
lovart text2image --help
lovart frames2video --help
lovart asset_upload --help

Command families:

• auth: auth login, auth logout, auth status
• image generation: text2image, image2image
• video generation: text2video, frames2video, multiref2video, videoedit
• task inspection: list_task, query_result
• assets: asset_upload, asset_list, asset_moderation_list
• tools: remove_background, runninghub_run
• interactive mode: lovart or lovart repl

Generator submits are successful only when the output includes ok: true and a non-empty submit_id. If a task is unfinished, query it later with the returned recommended_command or:

lovart --json query_result --submit-id <submit_id>

Examples

List recent generation tasks:

lovart list_task

Query one generation result:

lovart query_result --submit-id job_123

Upload one moderated asset:

lovart asset_upload --asset-type image --source ./person.png

Remove image background:

lovart remove_background --image ./product.png
lovart remove_background --image ./product.png --provider runninghub --api-key "$RUNNINGHUB_API_KEY"

Generate an image:

lovart text2image --prompt "A cinematic mountain lake at dawn" --ratio 16:9 --resolution-type 2K

Generate an image with GPT Image 2 width/height mode:

lovart text2image --prompt "Poster design" --model-version "GPT Image 2" --width 1536 --height 1024

Generate a video:

lovart text2video --prompt "A slow dolly through a neon city street" --model-version "Seedance Pro 1.5" --ratio 16:9 --quality 720p --duration 5

Request JSON output:

lovart --json text2image --prompt "Poster design" --ratio 1:1

Local File Inputs

Generator commands accept public URLs, asset://... references, and local file paths. When a generator command receives a local file path, the CLI uploads it first and sends the resulting public URL to the local service.

asset_upload uses a separate moderated asset path:

• --source accepts one public URL or one local file path
• local files are uploaded to COS first
• the CLI then submits the resulting network URL to POST /v1/kit/assets/upload
• the returned result can include asset_uri, asset_url, asset_id, channel_asset_id, and moderation_status

Local Checks

npm run smoke
npm test
node --check src/index.js
node src/index.js auth status
node src/index.js text2image --help

Commands that submit generation jobs contact the local Lovart service. If the service is not running, JSON mode should return a structured error instead of a Node.js stack trace.