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>:

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:

Music fields:

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

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.