Skip to main content

Crate amagi

Crate amagi 

Source
Expand description

§amagi

Chinese README: README.zh-CN.md

amagi is a Rust SDK, CLI, and JSON Web API service for multi-platform social web adapters.

§What It Does

  • Run CLI tasks against Bilibili, Douyin, Kuaishou, Twitter/X, and Xiaohongshu
  • Start a local JSON Web API with amagi serve
  • Reuse the same capability as a Rust crate with feature flags

§Quick Start

Install the latest release:

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/bandange/amagi-rs/main/scripts/install.sh | bash

PowerShell:

irm https://raw.githubusercontent.com/bandange/amagi-rs/main/scripts/install.ps1 | iex

Use proxy mode:

Linux/macOS:

curl -fsSL https://gh-proxy.com/https://raw.githubusercontent.com/bandange/amagi-rs/main/scripts/install.sh | bash -s -- --proxy

PowerShell:

& ([scriptblock]::Create((irm "https://gh-proxy.com/https://raw.githubusercontent.com/bandange/amagi-rs/main/scripts/install.ps1"))) -Proxy

Verify:

amagi --version

Common examples:

amagi run douyin video-work <aweme_id>
amagi run bilibili emoji-list
amagi run twitter user-profile <screen_name>
amagi serve --host 127.0.0.1 --port 4567

For install, update, uninstall, and shell integration details, see the installation guide.

§Run From Source

If you do not want to install the binary, run it directly in the repository. This requires a local Rust toolchain.

cargo run -- run
cargo run -- run douyin video-work <aweme_id>
cargo run -- serve --host 127.0.0.1 --port 4567

§Configuration

Configuration is loaded in this order:

  1. the user-level dotenv file
  2. the current directory .env

User-level dotenv path:

  • Linux/macOS: ~/.config/amagi/.env
  • Windows: %APPDATA%\\amagi\\.env

Useful files and variables:

  • .env.example
  • AMAGI_USER_ENV_FILE
  • AMAGI_DOUYIN_COOKIE
  • AMAGI_BILIBILI_COOKIE
  • AMAGI_KUAISHOU_COOKIE
  • AMAGI_TWITTER_COOKIE
  • AMAGI_XIAOHONGSHU_COOKIE
  • AMAGI_HOST
  • AMAGI_PORT

For the full environment and CLI option list, see the CLI reference.

§Crate Features

Default features: client, cli, server

Optional features:

  • catalog: static catalog and route metadata only
  • client: Rust client types and upstream fetchers
  • cli: command-line runtime
  • server: Axum-based HTTP service

Example:

amagi = { version = "0.1.4", default-features = false, features = ["client"] }

§Documentation

Chinese documentation:

Re-exports§

pub use catalog::ApiMethodSpec;
pub use catalog::HttpMethod;
pub use catalog::ParsePlatformError;
pub use catalog::Platform;
pub use catalog::PlatformSpec;
pub use catalog::all_platform_specs;
pub use catalog::find_method;
pub use catalog::get_api_route;
pub use catalog::get_chinese_method_name;
pub use catalog::get_english_method_name;
pub use catalog::method_specs;
pub use catalog::platform_spec;
pub use client::AmagiClient;
pub use client::ClientOptions;
pub use client::CookieConfig;
pub use client::PlatformClient;
pub use client::RequestConfig;
pub use client::RequestProfile;
pub use client::create_amagi_client;
pub use error::AppError;
pub use events::AmagiEvent;
pub use events::AmagiEventType;
pub use events::ApiErrorEventData;
pub use events::ApiSuccessEventData;
pub use events::EventBus;
pub use events::EventLogLevel;
pub use events::HttpRequestEventData;
pub use events::HttpResponseEventData;
pub use events::LogEventData;
pub use events::NetworkErrorEventData;
pub use events::NetworkRetryEventData;
pub use platforms::bilibili;
pub use platforms::douyin;
pub use platforms::kuaishou;
pub use platforms::twitter;
pub use platforms::xiaohongshu;

Modules§

app
Application runtime and top-level command dispatch for a resolved config::AppConfig. Application runtime orchestration for CLI and server modes.
catalog
Shared catalog metadata and route descriptors for the client and server surfaces. Shared catalog metadata and route descriptors.
cli
Command-line argument parsing and conversion into config::AppConfig. Parse CLI arguments and convert them into runtime configuration values.
client
Client configuration and platform accessors. SDK-style client configuration and platform accessors.
config
Shared configuration types used by the CLI, runtime, and HTTP server. Shared configuration types used by the CLI, runtime, and HTTP server.
env
.env loading and environment resolution helpers shared across runtimes. Layered dotenv loading and environment resolution helpers.
error
Shared error types used across the crate. Error types shared across crate entrypoints and runtime helpers.
events
Typed event bus shared across the client, CLI, and server flows. Typed event bus shared across SDK, CLI, and web flows.
output
Human-readable and machine-readable output helpers. User-facing startup output for text and JSON modes.
platforms
Rust-native platform fetchers and shared upstream transport adapters. Rust-native platform fetchers and shared upstream transport helpers.
server
HTTP server entrypoint, router, and handlers. HTTP server bootstrap, routing, and request handlers.
telemetry
Structured telemetry setup backed by tracing. Global tracing subscriber initialization and runtime telemetry defaults.

Constants§

APP_NAME
Crate name used by CLI output and server metadata.
DEFAULT_HOST
Default host used by the built-in HTTP server.
DEFAULT_PORT
Default port used by the built-in HTTP server.

Functions§

print_startup_error
Print an error::AppError in a human-friendly fallback format.
run_env
Parse process arguments and run the application.