pi-tube

pi-tube is a Bun + TypeScript CLI for turning media inputs into structured artifacts.

Current delivery status: Phase 7 CLI UX overhaul is active (scoped help, friendly config aliases, and setup automation parity).

Install (macOS/Linux)

npm install (published package)

npm install -g @syxs/pi-tube

Or without global install:

npx -y @syxs/pi-tube --help

Quick install

curl -fsSL https://raw.githubusercontent.com/Lag0/pi-tube/main/install.sh | bash

Local dev install

git clone https://github.com/Lag0/pi-tube.git
cd pi-tube
bun install

Run

pi-tube --help
pi-tube help config
pi-tube --version
pi-tube <input>
pi-tube setup install
pi-tube setup skills

Help Contract (Phase 5)

The top-level help is intentionally fixed in this order:

1. Usage
2. Commands
3. Global options
4. Examples
5. Notes

Command Surface

Implemented now:

• pi-tube <input>
• pi-tube --json <input>
• pi-tube --provider <deepgram|groq> <input>
• pi-tube --language <code> <input>
• pi-tube --timestamps <input> (optional timestamp blocks, default off)
• pi-tube setup install
• pi-tube setup skills [--global] [--agent <name>] [--yes|--no-prompt]
• pi-tube config set <key> <value>
• pi-tube config get <key>
• pi-tube config list
• pi-tube config provider set <deepgram|groq>
• pi-tube config provider env <deepgram|groq> <ENV_VAR>
• pi-tube config language set <code>
• pi-tube provider-status
• pi-tube --json provider-status
• pi-tube --help
• pi-tube --version

Deferred command aliases (non-zero guidance, use baseline input path):

• pi-tube youtube <url> (use pi-tube <input>)
• pi-tube instagram <url> (use pi-tube <input>)

Examples

pi-tube "https://youtube.com/watch?v=dQw4w9WgXcQ"   # active
pi-tube --provider deepgram "https://youtube.com/watch?v=dQw4w9WgXcQ"  # active
pi-tube --provider groq --language pt "./recording.mp3"                # active
pi-tube --timestamps "https://youtube.com/watch?v=dQw4w9WgXcQ"         # include timestamp blocks
pi-tube "https://instagram.com/reel/abc123"         # active (public URLs only)
pi-tube "https://cdn.example.com/audio/demo.wav"    # active
pi-tube "./recording.mp3"                           # active
pi-tube --json "https://youtube.com/watch?v=dQw4w9WgXcQ"  # active JSON output
pi-tube setup install                                      # npm install/setup guidance
pi-tube setup skills                                       # interactive default (human flow)
pi-tube setup skills --global                              # interactive global scope
pi-tube setup skills --agent codex                         # install for a specific agent
pi-tube setup skills --global --yes                        # non-interactive automation path
pi-tube setup skills --global --no-prompt                  # alias for non-interactive mode
pi-tube config set defaults.provider groq                 # active config flow
pi-tube config set providers.groq.api_key_env GROQ_API_KEY
pi-tube config provider set groq                          # friendly provider alias
pi-tube config provider env groq GROQ_API_KEY             # friendly env alias
pi-tube config language set pt-BR                         # friendly language alias
pi-tube config list
pi-tube provider-status                                   # active provider readiness
pi-tube --json provider-status                            # active readiness JSON

Config Keys and Precedence

Supported configuration keys:

• defaults.provider (deepgram or groq)
• defaults.language (language code)
• providers.deepgram.api_key
• providers.deepgram.api_key_env
• providers.groq.api_key
• providers.groq.api_key_env

Friendly aliases (mapped to the same canonical keys):

• pi-tube config provider set <deepgram|groq> → defaults.provider
• pi-tube config provider env <provider> <ENV_VAR> → providers.<provider>.api_key_env
• pi-tube config provider key <provider> <api_key> → providers.<provider>.api_key
• pi-tube config language set <code> → defaults.language

Legacy config set/get/list dot-path commands remain supported for existing scripts.

Default config file path:

• ~/.pi-tube/config.json (override with PI_TUBE_CONFIG_PATH)

Resolution precedence:

• Provider: CLI --provider > config defaults.provider > PI_TUBE_TRANSCRIPTION_PROVIDER > deepgram
• Language: CLI --language > config defaults.language > PI_TUBE_TRANSCRIPTION_LANGUAGE
• API key: config providers.<id>.api_key > env referenced by providers.<id>.api_key_env > default provider env (DEEPGRAM_API_KEY/GROQ_API_KEY)

Agent Workflows

• Default output is deterministic Markdown with YAML frontmatter, extractive summary, and transcript sections.
• Baseline runs write artifacts to ~/.pi-tube/YYYY-MM-DD-<title-or-file>.{md|json} by default.
• Stdout prints [OUTPUT_FILE] and [OUTPUT_FILE_URI] so you can click/open the generated file from terminal output.
• Timestamp blocks are disabled by default to reduce artifact size/context; use --timestamps when needed.
• --json emits a deterministic schema-versioned contract from the same canonical artifact model.
• provider-status reports registered providers and missing required env vars in deterministic text or JSON.
• setup skills installs the repository skill bundle (skills/pi-tube) into supported agent tooling.
• setup skills follows Firecrawl-style behavior: interactive default, optional --global and --agent.
• Use setup skills --global --yes (or --no-prompt) for non-interactive AI/automation setup.
• Temporary media downloads for YouTube/Instagram transcription use ~/.pi-tube/tmp and are deleted after each run (success or error).

Release Hardening

Before tagging a release, run the mandatory checks in docs/release-checklist.md.

npm publish automation is defined in .github/workflows/publish.yml with provenance and version-exists checks.

Instagram Public-Only Policy

Before tagging a release, run the mandatory checks in docs/release-checklist.md.

npm publish automation is defined in .github/workflows/publish.yml with provenance and version-exists checks.

Instagram Public-Only Policy

• Supported URL classes: Instagram public post/reel/video URLs (for example /p/..., /reel/..., /tv/...).
• Auth-gated Instagram inputs fail with INSTAGRAM_AUTH_REQUIRED.
• CLI exits non-zero on auth-required failures and prints remediation guidance to use publicly accessible URLs.

Runtime Policy

The primary runtime path is Bun + TypeScript. Python runtime is not required for the v1 default path.

Legacy command patterns are still recognized for compatibility messaging only and do not route back to Python behavior.

Provider Error Contract

Provider-layer failures are normalized to deterministic public codes:

• TRANSCRIPTION_PROVIDER_AUTH
• TRANSCRIPTION_PROVIDER_RATE_LIMIT
• TRANSCRIPTION_PROVIDER_UNAVAILABLE
• TRANSCRIPTION_PROVIDER_FAILED
• TRANSCRIPTION_PROVIDER_INVALID_RESPONSE