Friendly command-line client for the OpenList API.
It supports both:
- high-level commands for common workflows
- low-level spec-driven commands for full API coverage
go install github.com/openlist/openlist-cli/cmd/openlist-cli@latestOr build from source:
make buildYou can configure the CLI with environment variables or local config.
| Variable | Default | Description |
|---|---|---|
OPENLIST_BASE_URL |
http://localhost:5244 |
OpenList server base URL |
OPENLIST_TOKEN |
(empty) | API token sent as the raw Authorization header |
OPENLIST_CLI_CONFIG |
platform default | Override config file path |
openlist-cli config set --base-url http://localhost:5244
openlist-cli config set --token 'your-fixed-admin-token'
openlist-cli config showDefault config path:
- macOS/Linux:
~/.config/openlist-cli/config.json
Priority order:
- command-line flags
- environment variables
- local config file
OpenList supports two token styles in practice:
- Login JWT from
/api/auth/login/hash- expires according to server-side
TOKEN_EXPIRES_IN
- expires according to server-side
- Fixed admin token from server settings
- does not expire automatically
- becomes invalid only if rotated/reset on the server
This CLI sends the token as the raw Authorization header value to match the server implementation.
openlist-cli <command> [flags]All commands support:
--jsonfor machine-readable output--plainfor stable plain-text output--jqonly together with--json
openlist-cli auth login --username admin --password 'secret'
openlist-cli auth token
openlist-cli auth whoami
openlist-cli auth logoutauth loginuses/api/auth/login/hash- plain passwords are hashed with SHA256 before sending
auth tokenprints the effective token, similar togh auth token
openlist-cli config show
openlist-cli config set --base-url http://localhost:5244
openlist-cli config set --token 'your-token'
openlist-cli config clear# List a directory
openlist-cli fs ls /
openlist-cli fs ls .
# Get file or directory metadata
openlist-cli fs stat /Movies/file.mkv
# Print a tree (default depth: 3)
openlist-cli fs tree /Movies
openlist-cli fs tree /Movies --depth 5
# Search
openlist-cli fs search --parent / --keywords movie
# Build OpenList download URLs
openlist-cli fs download-url /Movies/file.mkv
openlist-cli fs download-url /Movies/file.mkv --proxy
openlist-cli fs download-url /Movies/file.mkv --raw-urlopenlist-cli share ls
openlist-cli share url abcdef123456
openlist-cli share url abcdef123456 dir/file.txt --archiveThese are useful when you want direct access to spec operations.
# List all OpenAPI operations
openlist-cli list-ops --plain
# Call any operation by operationId
openlist-cli call fsList --body '{"path":"/"}' --json
openlist-cli call ping --json
# Build non-JSON route URLs
openlist-cli route direct-url --path '/Movies/file.mkv' --sign 'BASE64:0'
openlist-cli route proxy-url --path '/Movies/file.mkv' --sign 'BASE64:0'
openlist-cli route archive-url --archive-path '/archive.zip' --inner 'a.txt' --sign 'SIG'
openlist-cli route share-url --sharing-id abcdef123456
# Fetch a URL or OpenList-relative route
openlist-cli fetch --url '/d/Movies/file.mkv?sign=BASE64:0' --output ./file.mkvUse a fixed token from environment variables:
export OPENLIST_BASE_URL='http://localhost:5244'
export OPENLIST_TOKEN='your-fixed-admin-token'
openlist-cli auth token
openlist-cli auth whoami
openlist-cli fs ls --path /Use login-based auth and save the returned JWT locally:
openlist-cli auth login --username admin --password 'secret'
openlist-cli auth whoamimake test # unit tests
make bdd # BDD/smoke tests
make ci # fmt check + vet + tests + build
make build # local binary
make cross-build # darwin/linux amd64/arm64
make clean # remove build artifactscmd/openlist-cli- entrypointinternal/app- CLI implementationinternal/spec- embedded OpenAPI spec and operation indexdocs/download-and-url-routes.md- non-JSON route referencedocs/openapi/- generated OpenAPI summary/plan/test matrix.github/workflows/- CI and release workflows
