Make a Video With Your Agent

Facet combines production instructions and media tools for your agentic CLI. Your coding agent plans the work and invokes tools. You supply the idea or footage, approve consequential choices, and review the result.

Start with a simple request such as "Make a short explainer about how rain forms" or "Turn my screen recording into a concise walkthrough." You do not need to specify JSON, tool names, or a rigid production sequence.

Use Facet with your agentic CLI. Tool configuration, completed media generation, and editorial acceptance are separate checks.

Recommended Installation

Use Facet with your agentic CLI. The interactive installer supports OpenCode, Codex, Claude Code, and GitHub Copilot CLI, and lets you choose the optional production tools you need.

Run the command for your platform in a terminal:

# Windows (PowerShell)
irm https://xibodev.github.io/facet/install.ps1 | iex

# Linux / macOS
curl -fsSL https://xibodev.github.io/facet/install.sh | sh

The website bootstrap downloads and checksum-verifies the v1.0.4 installer package, then launches its interactive installer. The installer selects the matching prebuilt Windows, Linux, or macOS bundle for x64 or ARM64. The Unix one-liner requires an interactive terminal for its prompts.

Manual Installation

Download the installer ZIP, extract it, and run ./install.ps1 in PowerShell or bash ./install.sh from the extracted folder. Keep its installer/ directory beside the scripts. Only the website bootstrap supports piping. See release assets and SHA-256 checksums for manual/offline downloads.

Use arrow keys and Enter to choose your CLI; Space toggles optional tools. Rerun setup to add components, repair, or update. For an existing v1.0.3 project, accept the explicit backup migration and choose update. Set FACET_PLAIN=1 for plain prompts.

1. Select your CLI and the project folder that should use Facet.
2. Choose optional dependencies from the list of capabilities and approximate download sizes.
3. Review the installation summary and any dependency installation commands.
4. Start a new agent session in the configured project and ask it to use Facet.

The installer uses prebuilt Facet binaries and preserves existing user instructions and project configuration. It assumes your CLI is already authenticated.

Optional Dependencies

Local editing and rendering do not require media-provider API keys. Optional generation services may require separate credentials, account access, or credits. The installer explains optional downloads, and tools report missing configuration when you use them.

• FFmpeg and FFprobe: core media editing and inspection.
• Remotion: animated compositions and rendered captions, with its browser and Node.js/npm dependencies.
• Piper: local speech synthesis, with an optional runtime and voice-model download.
• gflow: optional image/video generation through its supported providers.
• HyperFrames: HTML-based video rendering.

Using Facet with Another Agent

Using a different agentic CLI? Ask your agent to inspect this repository and adapt Facet's skills and command-line tools to its own integration conventions. The installer currently supports the four CLIs listed above; other integrations are community-adapted and may need additional setup.

Verify the Setup, Then Review the Work

The CLI-only installer runs local media checks for the selected components unless verification is explicitly skipped. Those checks do not test external provider access or establish editorial quality.

Review the actual video, audio, captions, and source material from your production before sharing it.

Standalone Status

Facet Standalone is experimental. For now, we recommend using Facet through a supported agentic CLI.

Use Your Agent in the Terminal

Open your selected CLI in the project configured by the installer and ask it to use the Facet skill.

Use Facet to make a short explainer about how rain forms.

Use a separate directory for each production. In your agent conversation, try "Add captions to my recording" or "Make the narration slower and leave more time on the diagram." Give it the actual source file location when editing existing media.

Ask the agent to explain provider choices and costs before paid work, and to report errors without substituting placeholders. Number of turns, render duration, and final quality depend on the request and environment.

Choose a Production Pack

The bundle contains the following packs. The Facet skill directs your agent to the relevant pack for the task. A pack supplies guidance and content, not proof that every referenced tool or provider is installed.

Explainer / @xibodev/facet-pack-explainer

Manifest: animated explainers, diagrams, charts, and text cards. Requires the Remotion runtime, browser, and usable narration route when speech is requested.

Cinematic / @xibodev/facet-pack-cinematic

Manifest: cinematic and documentary montages. Needs supplied or accessible source media with suitable rights; generated clips need configured providers.

Screen Demo / @xibodev/facet-pack-screendemo

Manifest: software walkthroughs and terminal scenes. Actual capture requires app access and recording/browser tooling; synthetic terminals must not be presented as real execution evidence.

Talking Head / @xibodev/facet-pack-talkinghead

Manifest: presenter edits and avatar workflows. Requires presenter footage or a separate avatar/lip-sync provider and consent. TTS alone does not generate a presenter.

Social / @xibodev/facet-pack-social

Manifest: vertical clips and podcast repurposing. Needs source media and accurate transcript/timing data for captions. Framing and moment selection need review; audience performance is not guaranteed.

Character Animation / @xibodev/facet-pack-animation

Manifest: rigs, pose libraries, and action timelines. Requires character assets, authoring, and a working renderer; no character-generation model is bundled by the pack.

Localization / @xibodev/facet-pack-localization

Manifest: translated voiceovers, subtitles, and dubbing. Requires source media, transcription/translation, and a target-language voice. Voice cloning or lip-sync needs separate provider support and consent; check translation and timing.

Optional gflow Integration

Facet's gflow_image and gflow_video tools call the optional gflow CLI. Select it during dependency setup if you need it. gflow supports extension-free provider routes; its help and error diagnostics explain the requirements of the provider you choose.

Setup or status success is not generation evidence. Quotas, credits, account eligibility, models, and service availability still apply. Facet does not promise zero-cost generation; unknown estimates or zero-valued generic metadata are not a billing guarantee.

Dependency, authentication, provider, timeout, and invalid-response errors should be investigated, not hidden by mock output. An explicit mock: true request creates test media; it is never proof of provider generation. A timed-out request may still be running remotely, so check before retrying.

Project Files Are the Durable Record

The CLI-only installer creates a project skill and .facet-install/ for its launcher, installation record, and pack references. Existing configuration is preserved. Scripts, scene plans, narration, renders, and review outputs appear only when the corresponding work runs.

my-video/
  assets/             # supplied or acquired media
  artifacts/          # scripts/plans/reports when produced
  narration/          # generated or supplied voice tracks
  renders/            # video and review outputs when produced
  .facet-install/     # installed launcher, record, and pack references
  .opencode/skills/facet/SKILL.md  # example host skill location

Skill locations depend on your CLI. Media directories and paths such as renders/final.mp4 are conventions, not a promise that installation creates a video.

Configuration can pin runtime paths in .facet.yaml or ~/.config/facet/config.yaml. Unpinned discovery looks near the working directory and executable, then in the user bundle. Reopening a project preserves pinned configuration. Verify rendering from that production folder rather than relying on a successful run inside the source checkout.

Known Limitations

• Installation is not acceptance. Local setup checks do not verify every workflow. Browser dependencies, fonts, pinned runtime paths, and provider access can still affect a production.
• Pack guidance is broader than the executable registry. Some routes reference optional tools, models, transcription, or browser integrations not supplied by the native CLI. Check the installed tool and its actual implementation before relying on it.
• Network services are conditional. Edge TTS is keyless but network-dependent. Other providers may need credentials and payment; model availability and account limits can change.
• Standalone is experimental. For now, we recommend using Facet through a supported agentic CLI.
• Automated review is partial. Technical media checks and sampled frames do not establish factual accuracy, language quality, consent, asset rights, or creative quality. Watch and listen to the output.

These pages do not certify a release or promise a finished video in a fixed number of turns or minutes.

Technical Reference

Most users can stay with natural-language prompts. Integrators should inspect the installed CLI and source contracts rather than copy an assumed universal scene payload.

facet help
facet init --help
facet ui --help
facet tools list
facet tools describe video_compose
facet tools describe output_review
facet tools estimate <tool-name> --input request.json
facet tools run <tool-name> --input request.json