Tinycloud

Agent CLI for deep video and image work. Point it at videos or images and ask for analysis, dashboards, subtitles, clips, search, or repurposed content — or drive its verbs directly from your own agent. Powered by Cloudglue. Learn more at tinycloud.sh.

Install

npm install -g @cloudglue/tinycloud     # then: tinycloud
npx @cloudglue/tinycloud                # or run directly

The npm package is a small launcher: on first run it downloads the matching platform distribution from Cloudglue's CDN (cached under ~/.tinycloud/versions/<version>/), verifies its checksum, and execs the real binary. The package version pins the binary version, so npx @cloudglue/[email protected] always runs tinycloud 0.3.25. It also adds two wrapper commands:

tinycloud install --version 0.3.25   # pre-download a version
tinycloud install --latest          # install latest stable and pin to it
tinycloud update                    # move to latest stable, prune old versions

Alternatively, the shell installer (installs to ~/.tinycloud/bin and adds it to your PATH):

curl -fsSL https://app.cloudglue.dev/tinycloud.sh | bash

Platforms: macOS (arm64, x64) and Linux (x64, arm64). Windows is not supported — use WSL2.

Setup

Cloud features need a Cloudglue API key. The quickest way is browser sign-in (0.3.10+) — it provisions a key for you, no copy-paste:

tinycloud login                             # browser sign-in → provisions & saves a key (0.3.10+)
# or paste a key yourself:
tinycloud setup cloudglue --api-key <key>   # or: export CLOUDGLUE_API_KEY=...
tinycloud setup --check --json              # verify

Use tinycloud from your agent

This repo also distributes agent skills that teach coding agents (Claude Code, Codex, and anything else following the Agent Skills standard) to drive the tinycloud CLI.

One command (in a terminal it prompts you to pick the target agents):

npx @cloudglue/tinycloud skills install                       # menu: claude-code, agents, codex, cursor
npx @cloudglue/tinycloud skills install --harness cursor,codex  # pick targets non-interactively
npx @cloudglue/tinycloud skills install --global              # ~/.claude/skills (Claude Code only)
npx @cloudglue/tinycloud skills install --skill tinycloud,blog-post   # just some

Each agent reads skills from its own <dir>/skills: claude-code → .claude, agents → .agents (the universal Agent Skills layout), codex → .codex, cursor → .cursor. The menu preselects dirs that already exist; piped/CI runs (or --yes) skip it and install into whichever dirs exist, defaulting to .claude/skills when none do.

Claude Code (as a plugin):

/plugin marketplace add cloudglue/tinycloud
/plugin install tinycloud@cloudglue

Also works with the generic installer (npx skills add cloudglue/tinycloud) or a plain copy (cp -r skills/* ~/.claude/skills/).

| Skill | What it does | |---|---| | tinycloud-init | First-time setup: install the CLI, configure the API key, verify with a free command | | tinycloud | The general skill: full CLI usage, JSON envelope contract, verbs, workflows, glossary, troubleshooting | | sales-coaching | Sales call → coaching dashboard (scores, speech metrics, objections) | | blog-post | Video → rich blog post with sections, thumbnails, takeaways | | ad-analysis | Video ad → shot timeline, hook, pacing, CTA breakdown | | meeting-breakdown | Meeting recording → speaker timeline, summaries, action items | | youtube-publish | Video → YouTube title, description, chapters, tags, subtitles | | tinycloud-skill-creator | Author your own tinycloud-powered skills (recipe + render script) |

New to tinycloud? Invoke tinycloud-init in your agent for guided setup. Each skill checks compatibility via the general skill's scripts/preflight.sh, which gates on the installed binary's version and feature ids (skills/tinycloud/tinycloud-skill.json declares the requirements).

Team setup

To give every agent session in a repo the same skills, commit them:

cd your-project
npx @cloudglue/tinycloud skills install --harness claude-code,agents   # or pick from the menu
git add .claude .agents .codex .cursor 2>/dev/null; git commit -m "Add tinycloud agent skills"

Optionally add a line to your project's CLAUDE.md so agents reach for them: Video work (analysis, captions, clips, workflows) goes through the tinycloud CLI — see the tinycloud skill; run tinycloud-init if the CLI isn't set up.

Commands

Cloud commands run through your configured Cloudglue API key (billed per the rate card); local and network commands are free. Every command prints a JSON envelope on stdout (logs go to stderr) — pass --json.

| Command | What it does | |---|---| | watch | Analyze a video → reusable cached context + Cloudglue-ready ref | | see | Analyze an image → reusable cached context + Cloudglue-ready ref (JPEG/PNG/WebP) | | extract | Pull structured facts, entities, or moments from a video or image (free-form or JSON-schema) | | caption | Subtitles and transcripts (SRT/VTT/ASS) | | search | Keyword search over cached video context | | probe | Semantic moment/video search over a Cloudglue scope | | ask | Grounded Q&A over one or more videos | | query | Analytical SQL / natural-language queries over collection structured data (0.3.17+) | | clip | ffmpeg-backed cut, thumbs, stitch, transcode, burn, split, audio, info | | grab | Download a remote video (YouTube, TikTok, Loom, direct) | | face | Detect faces in a video, or match/search a known face, ranked by similarity | | library | Build & query Cloudglue collections (create/add/remove/delete) and browse connectors | | jobs | Poll, wait on, or forget async jobs | | workflow | Run packaged pipeline recipes (see below) | | publish | Publish HTML artifacts as Cloudglue Sites (playback embeds everywhere; private sites add live chat/search/query/transcript elements); share videos | | setup | Configure the Cloudglue API key and service connections | | login | Browser sign-in — provisions & saves a Cloudglue API key (0.3.10+) |

A few common invocations:

# Analyze a video into reusable, cached context + a Cloudglue-ready ref
tinycloud watch ./demo.mp4 --json
# Describe an image — the file-level counterpart of watch (JPEG/PNG/WebP)
tinycloud see ./photo.jpg --json
# Pull structured findings (free-form query here; pass --schema for a fixed shape)
tinycloud extract "key moments with timestamps" ./demo.mp4 --json
# extract also works on an image source (no segment/shot flags on images)
tinycloud extract "on-screen text and key objects" ./photo.png --json
# Subtitles plus a markdown transcript
tinycloud caption ./demo.mp4 --format srt --transcript --json
# Trim a clip locally — no upload, ffmpeg-backed
tinycloud clip cut ./demo.mp4 --start 12 --end 28 -o clip.mp4 --json
# Grounded Q&A over one or more videos
tinycloud ask "What objections came up?" --in ./demo.mp4 --json
# Analytics over a collection — SQL or plain English (0.3.17+)
tinycloud query "how many videos per source platform?" --in collection:col_123 --json
# Detect faces, or match a known face against a video (0.3.4+; query image: JPEG/PNG)
tinycloud face match ./person.jpg ./demo.mp4 --max-faces 10 --json

Collections (0.3.4+) turn a set of videos into a reusable, queryable knowledge base. Build one and query it — every type follows the same create → add → poll show → query → delete shape, differing only in --type and the verb that reads it:

tinycloud library collections create "calls" --type media-descriptions --json
tinycloud library collections add ./call.mp4 --to col_123 --json   # enrichment is async
tinycloud library collections show col_123 --json                  # poll files[].status → completed
tinycloud ask "What did customers object to?" --in collection:col_123 --json

media-descriptions backs ask/probe/search, face-analysis backs face list/face search, and entities (created with --prompt/--schema) backs library collections entities. Any collection is also queryable with query (0.3.17+) — read-only SQL or natural language over its files, metadata, and extracted entities (tinycloud query schema shows what's queryable).

tinycloud commands --json is the authoritative, machine-readable list of every command and flag. Full per-verb flags and cost classes: skills/tinycloud/reference/verbs.md. The envelope contract — statuses (ready, pending, needs_credentials, …) and exit codes: skills/tinycloud/reference/envelope.md.

Global flags & profiles (0.3.3+)

A few options are host-level — they isolate state rather than run a video operation, so they go before the verb and don't appear in commands --json:

• --home <dir> (or $TINYCLOUD_HOME) — run against an isolated state home (config, sessions, cache, jobs, artifacts, skills) instead of ~/.tinycloud.
• --profile <name> — use a named profile's home, so multiple accounts or installs run side by side without cross-contamination.

tinycloud --home ./.tc watch ./demo.mp4 --json      # isolated state for this repo
tinycloud profile list                              # profiles and their homes
tinycloud profile create work --default             # create one and make it default
tinycloud profile create staging --copy-from work   # clone an existing home
tinycloud --profile work ask "..." --in ./demo.mp4 --json

Sessions are scoped per project (keyed by the git root), the agent takes a --skills <list> allowlist alongside --tools, and a project-local .tinycloud/config.json can pin tool/skill allowlists and an output base. Details: skills/tinycloud/reference/setup.md.

Workflows

Workflows are packaged, repeatable pipelines that run with a single command and write their outputs into a run directory under ./tinycloud-output/runs/<run_id>/. The five flagship recipes — each with a matching agent skill — are:

| Workflow | Turns a video into | |---|---| | sales-coaching | Coaching dashboard — call scores, speech metrics, objections | | blog-post | Rich blog post — sections, thumbnails, takeaways | | ad-analysis | Ad breakdown — shot timeline, hook, pacing, CTA | | meeting-breakdown | Speaker timeline, chapter summaries, action items | | youtube-publish | YouTube title, description, chapters, tags, subtitles |

tinycloud workflow list --json                       # all available recipes
tinycloud workflow sales-coaching ./call.mp4 --json  # run one
tinycloud workflow plan blog-post ./demo.mp4 --json  # preview steps (free, no side effects)
tinycloud workflow validate ad-analysis --json       # check a recipe (or a path)

The final envelope reports data.status (completed | partial | failed | paused), data.outputs (named outputs such as outputs.html), and data.artifacts[].path. The five above each have a matching agent skill (see the table), so coding agents can run them directly; tinycloud workflow list shows the full set, including building blocks like summary and clip-highlights. Author your own recipes: skills/tinycloud/reference/workflow-authoring.md (or scaffold one with the tinycloud-skill-creator skill).

License

© Aviary Inc. (d/b/a Cloudglue). All rights reserved. Use is subject to Aviary Inc. Terms of Service.