savextube-cli 0.1.4

SaveXTube 命令行客户端

SaveXTube CLI

sxt is the lightweight open CLI client for a running SaveXTube server. It covers basic automation-friendly workflows: login, submit downloads, inspect jobs, retrieve completed files, manage simple subscriptions, update common settings, monitor status, and read logs.

Installation

pipx install savextube-cli

Or install it into the current Python environment:

python -m pip install savextube-cli

For local development:

python -m pip install -e .
sxt --version

Commands

sxt login
sxt login http://nas.local:8530
sxt login http://nas.local:8530 -u admin -p admin
sxt logout
sxt whoami
sxt whoami --json

sxt dl 'URL'
sxt dl 'URL' --json
sxt dl 'URL' --wait --json
sxt dl 'URL' --transfer
sxt dl 'URL' --transfer --delete-source
sxt job list
sxt job list --json
sxt job show JOB_ID
sxt job show JOB_ID --json
sxt job show JOB_ID --files
sxt job show JOB_ID -f 1 --json
sxt job save JOB_ID
sxt job save JOB_ID --file 1
sxt job del JOB_ID
sxt job del --all --yes

sxt his list
sxt his list --json
sxt his show ID
sxt his show ID --json
sxt his show ID --files
sxt his show ID -f 3
sxt his show ID -f 3 --json
sxt his video save ID
sxt his video save ID --file 1
sxt his asr ID
sxt his asr ID --status --json
sxt his asr ID --wait --json
sxt his asr ID --force --wait --json
sxt his asr save ID
sxt his asr save ID -o ./transcript.md --json
sxt his del ID
sxt his del --all --yes

sxt sub list
sxt sub list --sub
sxt sub list --fav
sxt sub list --fav --json
sxt sub add 'URL' -p Bilibili -i 60 -m video -t sub
sxt sub add 'BILIBILI_FAVORITES_URL' -t fav -i 60
sxt sub fav 'BILIBILI_FAVORITES_URL' -i 60
sxt sub run ID --json
sxt sub toggle ID
sxt sub del ID

sxt set list
sxt set list --json
sxt set get youtube.download_cover
sxt set get youtube.download_cover --json
sxt set youtube.download_cover true
sxt set import ./savextube.toml
sxt set export ./savextube.toml
sxt set proxy http://127.0.0.1:7890
sxt set qb get host
sxt set qb host 192.168.2.134
sxt set qb port 8988
sxt set cookie list
sxt set cookie show youtube
sxt set cookie update youtube ./cookies.txt
sxt set wechat scan
sxt set wechat status
sxt set wechat relogin
sxt set wechat stop
sxt set wechat reply on
sxt set wechat delete-source off

sxt key list
sxt key list --json
sxt key add "自动化脚本"
sxt key add "自动化脚本" --json
sxt key toggle 1
sxt key del 1 --yes

sxt mon list
sxt mon list -w
sxt mon list --user USERNAME
sxt mon list --json

sxt log
sxt log --json
sxt log -f

sxt completion zsh
sxt completion bash
sxt completion fish

sxt job show JOB_ID and sxt his show ID display album metadata when available: artist, audio quality, bitrate, format, save location, track count, total size, and the track file list.

Add --json to query commands when another agent or script needs stable machine-readable output. sxt dl --json is also supported because it returns the job_id used by follow-up automation. Mutation-only commands rely on exit status for scripts.

ASR automation

Configure the user's ASR provider in Web Settings first. The CLI deliberately does not accept API keys, so credentials do not leak into shell history.

An agent or Skill can use this flow:

# Find a completed single-file video/audio history item.
sxt his list --json

# Start transcription and wait for the terminal status.
sxt his asr 123 --wait --timeout 3600 --json

# Inspect the current or completed status without starting a new task.
sxt his asr 123 --status --json

# Download the generated Markdown.
sxt his asr save 123 -o ./video-transcript.md --json

Direct HTTP API equivalents, authenticated with Authorization: Bearer <JWT>:

Method	Path	Purpose
POST	/api/asr/test	Test an ASR form configuration
POST	/api/history/<id>/transcription	Start transcription; JSON body supports force
GET	/api/history/<id>/transcription	Read status and progress
GET	/api/history/<id>/transcription/download	Download Markdown

sxt his asr --wait --json returns submitted and transcription. The transcription object contains status, progress, provider, model, language, error, has_result, and updated_at. A failed terminal status also makes the command exit non-zero.

JSON contract

--json output is UTF-8 JSON with original API fields preserved. Scripts should prefer the normalized fields below when present.

Common item fields:

Field	Meaning
id	Download job ID or history ID
title	Display title
platform	Platform name
status	Current status, such as done, failed, running
url	Original source URL
content_type	Main media type: video, image, music, or service value
item_type	Music subtype when available: track, album, playlist
type_label	Human-readable type label
file_path	Main saved path
file_size	Total size in bytes when available
files_count	Number of files/tracks/images
files	File list
meta	Raw metadata object from history storage

Music fields:

Field	Meaning
artist	Artist name
quality_name	Audio quality label, such as 无损
bitrate	Audio format detail, such as 16bit/44.1kHz/993kbps
format	Container or codec format, such as FLAC

File fields from sxt job show JOB_ID -f N --json or sxt his show ID -f N --json:

Field	Meaning
index	File index used by --file
filename	File name
path	Saved file path
size	File size in bytes
size_text	Human-readable file size
title	Parent item title
platform	Parent item platform
item_type	Parent item type
artist	Parent artist when available
quality_name	Parent audio quality when available
bitrate	Parent bitrate when available
format	File format
created_at	Parent creation time
url	Parent source URL

Configuration

The CLI stores its server URL and JWT token in:

~/.config/savextube/cli.json

Environment variables override the saved config:

SXT_SERVER=http://nas.local:8530
SXT_TOKEN=...
SXT_CONFIG_DIR=/tmp/sxt-test

Scope

The CLI intentionally stays small. Pro-style administration and visual workflows, such as full user management, invite-code administration, cookie editing, widget layout, and advanced security setup, belong in the Web UI.