Amir CLI 🚀

Amir CLI is a powerful, all-in-one terminal assistant designed for simplicity, automation, and productivity. It streamlines your daily workflow by bringing together advanced video compression, system maintenance, AI integration, and file management into a single, cohesive command-line interface.

Built with modularity and ease of use in mind, amir works seamlessly across macOS, Linux, and Windows (via WSL/Git Bash).

✨ Features

• 🎬 Smart Video Processing: Compress, cut (multi-range single-pass), convert formats, picture-in-picture overlay, screen recording, and concat with mixed-codec support (H.264 + HEVC MOV). Auto-detects hardware (Apple Silicon VideoToolbox), handles Apple HEVC hvc1 correctly.
• 🧠 Skill Management: amir skill harvest searches GitHub by stars, fetches READMEs, and synthesizes .agent/skills/ reference files for AI agents. Covers YouTube automation, TTS (Fish Speech, GPT-SoVITS, XTTS v2), video production, ComfyUI, music generation, and analytics.
• 🖼️ Advanced Image Processing: AI-powered upscaling (Real-ESRGAN), document enhancement lab (140 variations), smart stacking (front/back), and professional corner rounding.
• 🌍 Advanced Subtitle System: AI-powered multilingual subtitles supporting 32 languages. Features automatic translation, multi-platform hardware encoding (Mac/Ubuntu) with 1:1 size parity, Whisper Turbo as default, and document export via --save (no argument defaults to pdf).
• 🤖 AI Powered: Chat with Gemini/Gemma, generate code, and fetch model lists from 5 LLM providers (Gemini, OpenAI, DeepSeek, Groq, Anthropic).
• 📡 Research & Trends: Multi-Agent RAG pipeline that searches YouTube, GitHub, arXiv, Reddit, ProductHunt, and Indie Hackers. Find trending content, filter by language/region, and generate cross-source ideas.
• 🛠️ System Utilities: One-command system cleanup, password generation, file locking/unlocking, and QR code generation.
• ☁️ File Transfer: Instantly upload files to temporary hosting services and get a shareable link.
• ⚡ Super Fast: Written in optimized Bash/Zsh with minimal overhead.

📦 Installation

Installing Amir CLI is fully automated. Just run the installer:

# 1. Download or clone this repository
git clone https://github.com/su6i/amir-cli.git
cd amir-cli

# 2. Run the automated installer
chmod +x install.sh
./install.sh

The installer will:

1. Link the amir executable to your system path.
2. Check for dependencies (FFmpeg, etc.) and offer to install them automatically.
3. Set up command auto-completion for Zsh.

Dependencies & Python Note 🐍

Amir CLI uses Python 3 for helper tasks (like data formatting and subtitle processing).

• Zero-setup philosophy: The installer (install.sh) automatically creates a unified Python virtual environment at the root ./.venv. No manual virtualenv management is required.

• System Requirements:

  • python3 (3.8+)
  • ffmpeg (for media tools)
  • bc (for calculations)
  • qrencode, uv and other system tools (the installer attempts to install them automatically where possible)

• uv-first execution: Where possible, amir and its subcommands use uv to manage and run Python dependencies (uv run).

• ExFAT & Storage Robustness: amir automatically handles storage on ExFAT drives (like SanDisk) by bypassing file-locking limitations and redirecting temporary data to external volumes when internal space is low.

If the installer cannot provision a private or git-hosted package referenced in requirements.txt, it will notify you with clear remediation steps.

3. Configuration & Installation

Simply run the installer to set up dependencies and API keys in one go:

chmod +x install.sh
./install.sh

During installation, you will be asked to provide the following API key for AI features:

Key	Purpose (Why do I need this?)	Get it here
GEMINI_API_KEY	Enables the amir chat command, smart summaries, and intelligent help responses.	Google AI Studio
DEEPSEEK_API_KEY	Powers the subtitle translation system for 32 languages. Optional: fallback to Gemini if not set.	DeepSeek Platform
OPENAI_API_KEY	For llm-lists openai command (optional).	OpenAI Platform
GROQ_API_KEY	For llm-lists groq command (optional).	Groq Console
ANTHROPIC_API_KEY	For llm-lists anthropic command (optional).	Anthropic Console

⚙️ Configuration

Amir CLI uses a centralized configuration file located at ~/.amir/config.yaml. This file is automatically created on first run with sensible defaults, but you can customize it to match your preferences.

Example Configuration:

pdf:
  radius: 10          # Corner radius for PDF generation
  rotate: 0           # Default rotation angle

compress:
  resolution: 720     # Target video height (480, 720, 1080)
  quality: 60         # Compression quality (0-100)

mp3:
  bitrate: 320        # Audio bitrate in kbps

img:
  default_size: 1080  # Default image resize target
  upscale_model: ultrasharp 
  upscale_scale: 4

qr:
  size: 10            # QR code module size

pass:
  length: 16          # Default password length

weather:
  default_city: Montpellier

todo:
  file: ~/.amir/todo_list.txt

short:
  provider: is.gd     # URL shortener (is.gd, tinyurl.com, da.gd)

All commands respect these defaults unless overridden by command-line arguments.

4. Other commands

Run amir help or just amir to see the available commands. You can also rename the executable to whatever you prefer (e.g., assist, do) to match your workflow.

🎬 Multimedia

Command	Description
amir video <URL> [opts]	Unified Download + Process: Download from YouTube & 1000+ sites with smart reuse (existing matching downloads are reused to avoid _2/_3 duplicates). Key flags: --subtitle en fa (Whisper AI), --yt-subs --translate -t en fa (platform subs → LLM translate), --sub-only (SRT only), --only-subs, --formats (list formats), --resolution <h> (explicit download height), --extreme (auto-min practical resolution), --keep-thumb, --cookies.
`amir video <file/dir> [--gpu	--cpu]`
amir video convert <file> [--to fmt] [-o out] [--reencode]	Convert video container format (MOV→MP4, MKV, WEBM, AVI). Defaults to stream-copy (instant, no quality loss). Handles Apple HEVC (hvc1) correctly — no tag mangling. --reencode forces H.264 re-encode via VideoToolbox.
amir video pip <main> --pip <file> [--start T] [--end T] [--pos tl|tr|bl|br|X:Y] [--size %] ...	Picture-in-picture overlay: place one or more videos on a main video at specific time windows and positions. Multiple --pip flags supported. Audio from each pip is mixed into the output during its active window.
amir video concat <files...> [-o out.mp4]	Concatenate multiple videos in the exact order provided. Uses filter_complex per-input decoding — handles mixed codecs (H.264 MP4 + HEVC MOV) without freeze artifacts. Creates <first>_merged.mp4 when -o is omitted. Alias: amir video merge ....
amir video cut <file> [opts]	Cut video segments without re-encoding (instant) or with rendering. Supports -d/--delete <start> <end> (repeatable — multiple ranges removed in a single pass) and -x/--extract <start> <end> to keep only that range. Multiple -d flags: amir video cut v.mp4 -d 00:01:10 00:01:22 -d 00:08:45 00:09:02 -o out.mp4.
amir video split <file> <mb>	Split an existing video into approximate MB chunks (keyframe-bound, non re-encode).
amir split <file> <mb>	Global splitter for both audio and video files (approximate MB chunks, no re-encode).
amir video tiktok <url> [opts]	TikTok-optimized wrapper around video download with the same subtitle/translate pipeline flags.
amir video stats	View AI learning statistics & compression history.
amir mp3 <file> [bitrate] [--split <MB>]	Extract high-quality MP3 audio from a video file and optionally split the output into chunks.
amir audio youtube <url> [format] [bitrate] [--split <MB>]	Download audio from YouTube (mp3/wav/ogg) and optionally split the final output into chunks.
amir img upscale <file> [scale] [model]	AI-Upscale or quality enhancement (1x mode).
amir img lab <file> [-s scale] [-m model]	Generate 60/420 enhancement variations for testing.
amir img stack <files> [opts]	Combine images vertically (A4/B5 presets + deskew).
amir img rotate <file> <angle>	Rotate image by degrees.
amir img convert <svg> [fmt] [size]	Convert SVG/Image to PNG/JPG. Supports Animated SVGs.
amir img resize <file> <size> [circle]	Resize. Optional circle crop (transparent corners).
amir img crop <file> [size] [--smart]	Smart Content-Aware Crop (Auto-detect subject) or Manual Crop.
amir img pad <file> <size> [color]	Resize & Fill with Color (Contain).
amir img round <file> [radius] [fmt]	Round image corners (PNG/JPG).
amir img extend <file> [opts]	Extend image borders (custom/auto color).
amir img deskew <file> [output]	Auto-straighten scanned documents.
amir img <file> <size> [g]	Legacy mode (detects resize vs crop).
amir pdf [files] [opts]	Multi-Engine PDF Generator: Render Markdown/Text/Images to PDF. Supports piping (e.g., `amir clip
amir watermark <file> [text]	Add watermark to image (auto-saved or -o output).
amir subtitle <file/URL> [options]	AI-Powered Multilingual Subtitles: Transcribe, translate (32 languages), and render. Source is auto-detected by default; practical default layout is source-top + Persian-bottom (--sub auto fa). Key flags: --yt-subs (force YouTube internal subs), --ass-input <srt/ass> (render from manual file; .srt files are automatically styled with Vazirmatn), --resolution <h> and --quality <0-100> (final render controls), `--style channel_brand_blue
amir video record [--list] [--screen N] [--audio N] [--fps N] [-o FILE]	Record screen to MP4 using macOS AVFoundation. --list shows available screens/audio devices. Ctrl+C to stop. Alias: amir video rec.
amir info <file>	Show detailed technical metadata for any file.

🧠 Skill Management

Command	Description
amir skill search <query> [--min-stars N]	Search GitHub for repos matching query, ranked by stars — discover tools worth learning.
amir skill harvest <query> [--pick N] [-o file]	Search GitHub → fetch top READMEs → synthesize a .agent/skills/ reference file for AI agents.
amir skill list [--grep PATTERN]	List all existing skill files in .agent/skills/ with descriptions.
amir skill show <name>	Display contents of a skill file.

📡 Research & Trends

Bridge to the Research Toolkit — a Multi-Agent RAG pipeline across 6 platforms.

Command	Description
amir trend	Most-viewed videos globally (YouTube trending, no keyword needed)
amir trend "AI tools"	Search YouTube for a topic, sorted by views
amir trend --region IR	Trending in Iran
amir trend "موزیک" --lang fa	Filter results in Persian language
amir trend "LLM" --source github --metric stars	Top GitHub repos by stars
amir trend "deep learning" --source arxiv	Academic papers (arXiv)
amir trend "devops" --source reddit --metric comments	Reddit posts by comments
amir trend "SaaS" --ideas	Generate AI-powered ideas from collected data
amir trend "ML" --semantic	Semantic (multilingual) vector search
amir research	Alias for amir trend

All options (Tab-complete supported):

Option	Values	Default
--source	youtube github arxiv reddit producthunt indiehackers	youtube
--lang	fa en de ar zh es fr ru ja ko tr pt hi	any
--region	IR US GB DE FR JP KR AU CA IN ...	global
--metric	views likes stars citations comments published_at	views
--limit	number	10
--semantic	flag	keyword search
--ideas	flag	—
--count	number (with --ideas)	10

Setup: Set RESEARCH_TOOLKIT_DIR in your .env if the toolkit is not at ~/@-github/research_toolkit:

export RESEARCH_TOOLKIT_DIR=/path/to/research_toolkit

🧠 AI & Productivity

Command	Description
amir chat "hello"	Ask the AI assistant a question.
amir code "fix this"	Request code generation or refactoring.
amir llm-lists <provider> [-e fmt]	NEW: Fetch model lists from LLM providers (gemini, openai, deepseek, groq, anthropic). Export to PDF/MD/JPG.
amir todo "task"	Add a task to the local to-do list.
amir todo list	Show all pending tasks.
amir todo done <n>	Remove task number <n> from the list.
amir todo clear	Clear all tasks.
amir dashboard	Show a system status dashboard (CPU, RAM, Space).

🛠 Utilities

Command	Description
amir transfer <file>	Upload file to temporary cloud storage & copy link.
amir qr <content>	Create QR Code (URL, WiFi, Email, Phone, Text).
amir short <url>	Shorten a long URL.
amir clip [input]	Piped Clipboard: Copies text/files to clipboard, or outputs clipboard content to stdout when piped (e.g., `amir clip
amir pass [len]	Generate a strong, random password.
amir lock <file>	Encrypt a file (GPG).
amir unlock <file>	Decrypt a file.
amir clean	Interactive cleanup menu — toggle items on/off with Space/numbers, navigate with ↑↓, confirm with Enter. Covers: Trash, User Caches, System Logs, VS Code workspaceStorage, macOS Aerials Screensaver, Claude Desktop VM.
amir speed	Test internet connection speed.
amir weather [city]	Check weather (specify city or use default).
amir keyboard [fr|en|fa|auto]	Show keyboard layout for Apple Compact keyboard. Flags: --opt (Option layer), --shift (Shift layer), --normal, --find <char> (locate any character), --auto (detect active OS layout). Alias: amir kb.
amir init-project [dir]	Scaffold the Agent Constitution (.agent/ rules, skills, workflows) into a new project directory.
amir sync-constitution [dir]	Sync .agent/ rules and skills from the agent-constitution repo into an existing project. Preserves project-specific files; migrates legacy .agents//.cursor/ directories automatically. Override source with AMIR_CONSTITUTION_PATH.

🤝 Contributing

Contributions are welcome! Please check the issues page or submit a Pull Request.