Publish to visotalk.com
Log in from the command line, then preview or publish a talk as an unlisted link or a public work on visotalk.com.
visotalk.com is where explainers are watched. If you work with the skill in your own harness, three commands put what you made there, next to the work of people who made theirs in the hosted agent:
npx visotalk@latest login # once: approve this machine in your browser
npx visotalk@latest preview doc.tsx --yes # an unlisted link: anyone who has it can watch, it is listed nowhere
npx visotalk@latest publish doc.tsx --category science --yes # public: the community, search and your channelWhat happens
preview and publish pack the project as a source bundle (what export writes) and upload it to your account. The
service builds it again itself, checks it as it checks every talk (qa, the licences of the media), and only then shows it: what viewers play is always a player
the service made, never a file you sent. The talk then also appears in your explainers on visotalk.com, where the hosted agent can go on with it.
Publishing the same document again updates the same talk, and what you wrote about it (description, category) stays. The project remembers its id in its work
directory (.visotalk/<id>/); a project whose work directory is gone is a new talk.
A work needs a channel name (--handle, 3 to 20 lower-case letters, digits or underscores), asked for the first time and kept for good: it is the address of your
channel, visotalk.com/@name, and the only thing of you that a viewer sees. A public work states its category: science, technology, nature, society,
history, literature or product.
What it asks of the talk
- Narration made. Run
visotalk prepare doc.tsxfirst. The service does not speak your lines. - A document and its media, nothing else. Pictures, clips and sounds sit under
media/with lower-case, hyphenated names, at most 100 MB in all. A document with files of its own (components, fonts) is not accepted yet; the command names the file before it uploads anything. - The rights. The command asks once whether you made, or may use and share, every picture, clip and sound, and shows the terms the media carry.
--yesanswers yes, so use it only when that is true. - An invited account. While the service is in its early phase, publishing is open to invited accounts; the command says so if yours is not one.
- At most 20 builds a day per account.
A build takes minutes. The command waits and prints Built. when it has passed (with the number of qa findings, if any); --no-wait returns once the upload is accepted and the talk stays private until you make it visible in your workbench.
Taking it back
Make a work private again, or delete it, from your workbench. Each machine that is logged in appears on the account page of visotalk.com, where its access can be revoked; visotalk logout revokes this one. Anyone can report a published work, and an operator may take it down.
The wire contract
The commands speak plain HTTP to VISOTALK_URL (default https://visotalk.com). Everything below is JSON except the upload, and every route after the login takes Authorization: Bearer vt_…. Errors are {"error": "code", "issues"?: [{"path": [], "message": "…"}]}.
| Route | Does |
|---|---|
POST /api/cli/auth/start {machine} | Starts a login: {deviceCode, userCode, url, interval, expiresIn}. Show the user url and userCode. No token needed |
POST /api/cli/auth/poll {deviceCode} | Every interval seconds: {status: "pending"}, or {status: "approved", token, email} once. 400 expired_token, 400 invalid_device_code |
GET /api/cli/whoami | {email, name, handle} of the token's account; 401 when it is revoked or expired |
DELETE /api/cli/token | Revokes the token that asks |
POST /api/cli/publish | A form: file (the .visotalk source bundle) and rights=confirmed. 201 {talkId, updated} with the build queued. 403 not_invited, 400 rights_not_confirmed, 413 too_large, 422 invalid_bundle, 422 unsupported, 422 voice_required, 409 run_in_progress, 409 not_queued, 429 daily_limit |
GET /api/cli/publish/{talkId} | {state: "building"}, {state: "built", title, qaIssues, visibility} or {state: "failed", error, detail} |
POST /api/cli/publish/{talkId}/visibility {mode, description?, category?, handle?} | mode is preview (a private talk becomes unlisted; an unlisted or public one stays) or publish (public, with a category). Answers the publication, or 409 handle_required, handle_reserved, handle_taken, assets_not_cleared, 403 taken_down |
A token is good for 180 days, at most ten are live for an account, and it opens these routes and nothing else.