In Settings → API tokens, create a token with read access. Add edit access when you want the assistant to change a timeline. Set HEAVENLY_API_TOKEN in your shell environment; the CLI never saves your token.
Use your shell's hidden-input prompt or secret manager. Keep tokens out of command arguments and scripts committed to Git.
Use a single terminal workflow to inspect projects, request edits, and connect your tools.
Keep the editing loop in your terminal
Read a timeline, describe the change, and inspect the result. Small edits apply immediately after confirmation; larger edits may return a proposal for you to review.
$nodeheavenly.mjstools
Tools include:
list_projects
get_timeline
ask_editor_agent
get_credits
Each tool includes its argument schema.
Available tools depend on token permissions.
Review changes before they run
Write commands require explicit confirmation. Timeline edits also use the server's revision checks, so an outdated timeline is refused rather than overwriting newer work.
$nodeheavenly.mjschatPROJECT_ID
› Add a marker at 5 seconds
Send this instruction and spend an AI credit?
Type yes:
/timeline read the current timeline
/credits check remaining credits
/exit close the session
Build a terminal workflow around Heavenly
Compose real account tools with your own scripts. Commands return JSON; errors use a nonzero exit status.
Interactive editing with confirmation for each instruction.
ask PROJECT_ID "instruction" --confirm
Sends one editing instruction; may spend credits and apply edits.
call TOOL '{"argument":"value"}' --confirm
Calls a named tool. Omit --confirm for read-only tools.
exec
Reads JSON lines from stdin; each write needs confirm:true.
--help
Prints usage offline.
In exec, each line is {"tool":"name","arguments":{}}. Each response is {"ok":true,"result":…} or {"ok":false,"error":…}. The client exits with status 1 on a failed line.
Permissions and account access +
Permissions and account access
Your token's read, edit, and publish scopes are enforced by Heavenly on every request. The CLI also refuses writes without confirmation. Publish tools require explicit confirmation in the tool arguments; inspect the schema with tools.
Account ownership, active-plan requirements, credits, daily limits, expiration, and revocation use the existing server rules. Tokens cannot manage billing or create other tokens.
Network failures never trigger an automatic retry. If a write times out, inspect the project before repeating it. The CLI edits cloud timeline metadata; it does not upload footage, render video locally, or run arbitrary shell commands.
