Metadata-Version: 2.4
Name: savextube-cli
Version: 0.1.4
Summary: SaveXTube 命令行客户端
Author: SaveXTube
License-Expression: MIT
Project-URL: Homepage, https://github.com/savextube/savextube
Keywords: savextube,download,cli
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: qrcode

# 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

```bash
pipx install savextube-cli
```

Or install it into the current Python environment:

```bash
python -m pip install savextube-cli
```

For local development:

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

## Commands

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

```bash
# 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:

```text
~/.config/savextube/cli.json
```

Environment variables override the saved config:

```bash
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.
