The tmc CLI - The Modding Community

Aún No Publicado

tmc es un cliente de línea de comandos para nuestra API pública de contenido. Crea, edita y elimina tus recursos, mods, servidores, artículos, comunidades, colecciones y grupos — y, porque es para lo que realmente se usa la API, sube archivos y publica versiones en un solo comando.

Python 3.10+Cero dependenciasLicencia MIT

tmc todavía no está publicado. No está en PyPI y no tiene repositorio público — hoy se instala desde una copia del código fuente, y esta página describe lo que la herramienta ya hace en lugar de anunciar un lanzamiento.

install.sh
# From the source checkout — there is nothing to build
pip install .
pip install '.[fast]'   # optional: cryptography, for faster signing
tmc --version       # tmc 1.1.0

# Keys are made under Account → API Keys
tmc auth login --token tmc_xxxxxxxxxxxx
tmc auth whoami

# …or read public items with no key at all
tmc mod list --anon --app 4 -o json

Un único paquete de biblioteca estándar, así que no hay nada que compilar ni nada que resolver — y cada comando, opción y código de salida está documentado.

Versiones

La Razón De Tener Una Herramienta

Publicar una versión a través de la API en crudo son cuatro peticiones en un orden concreto: subir los archivos, recoger sus ids, leer el conjunto de versiones que ya existe y luego escribir la nueva sin tocar las demás. release publish es esa secuencia.

publish.sh
# Upload the files, attach them, write the release — one command
tmc release publish --mod 5 \
  --version 1.2.0 \
  --title "Bug fixes" \
  --content-file CHANGELOG.md \
  --file 'dist/*.zip' --file dist/checksums.txt

# Everything on the item, without re-sending the item
tmc release list  --mod 5
tmc release files --mod 5 --version 1.2.0

Volver A Ejecutarlo Actualiza

La misma --version dos veces actualiza esa versión y fusiona los archivos nuevos en su conjunto. Tus otras versiones no se tocan nunca, y una versión oculta sigue oculta.

Globs, Por Lotes

Pasa --file 'dist/*.zip' y tantos archivos como tengas; el límite de veinte subidas por petición se gestiona por ti.

Los Archivos Grandes Se Transmiten

Una subida de 1 GB se lee del disco por trozos, no en memoria. Todo lo que supere el límite de tamaño de tu clave se señala antes de enviarse.
Qué Hace

Todo Lo Que Hace La API, Bien Explicado

Un comando por cada cosa que harías en el navegador, y unas cuantas que no querrías hacer allí: ediciones masivas, pipelines y publicaciones automatizadas.

Sin Dependencias De Ningún Tipo

Python 3.10+ y la biblioteca estándar. Déjalo en una máquina de compilación o en un servidor de juego sin índice de paquetes y funciona. Usa cryptography para firmar si resulta estar instalada, y una implementación de RFC 8032 incluida si no lo está — las mismas firmas en ambos casos.

Ambos Modos De Autenticación

Claves Bearer tmc_, o aserciones firmadas con Ed25519 donde tú guardas la clave privada y nosotros solo almacenamos la mitad pública.

Una Gramática Para Cada Tipo

Los mismos cinco verbos — list, get, create, update, delete — sobre los catorce tipos, doce de los cuales tienen su propio comando. tmc content <tipo> es la forma uniforme, y la única vía hacia los tipos independientes release y media.

Relaciones Sin Reenviarlo Todo

Etiquetas, medios, versiones, enlaces, fuentes y elementos de colección se gestionan por su cuenta, así que añadir una captura no significa reescribir el elemento entero.

Operaciones Masivas, Dentro De Cada Límite

Crea o edita desde un archivo JSON de cualquier longitud. Cada límite del servidor —25 por escritura, 100 por borrado, 200 miembros de relación, 500 claves al borrar una relación, 20 partes de subida— se agrupa por ti, y un fallo parcial nombra el elemento que falló para que puedas continuar en lugar de empezar de cero.

Erratas Detectadas En Local

Los nombres de campo se comprueban contra una copia local de los esquemas de la API, con la sugerencia más cercana: 'mod' no tiene el campo 'tgs'. ¿Querías decir 'tags'? tmc schema mod imprime la lista de campos contra la que está comprobando.

Hecho Para Tuberías

Siete formatos de salida — table, json, jsonl, csv, tsv, yaml, ids — con --field para quedarte solo con las columnas que quieras. Datos por stdout, progreso por stderr, y tmc completion bash|zsh|fish para el shell que estés usando.

Límites De Tasa Gestionados

Un 429 se espera exactamente el tiempo que pide la API, hasta --retry-wait-max, y luego te dice cuánto queda en lugar de dejar colgada una compilación. El backoff se aplica solo a métodos idempotentes — un POST nunca se repite en silencio.
Credenciales

Claves, Perfiles Y La Mitad Pública

Inicia sesión una vez y la credencial se guarda en ~/.config/tmc/config.json con permisos 0600 — o pásala por el entorno y no se toca el disco en absoluto. Un perfil por sitio o por clave, y --anon para la mitad de la API que no necesita ninguna clave.

auth.sh
# A bearer key, or an Ed25519 key you hold the private half of
tmc auth login --token tmc_xxxxxxxxxxxx
tmc auth login --jwt --key-id tmcak_xxxxxxxx --private-key ~/keys/tmc.pem

# A second key on the same site — a scoped one for scripts
tmc auth login --profile ci \
  --base-url https://moddingcommunity.com --token tmc_…
tmc auth use ci

# Which key is active, and what the server lets it do
tmc auth whoami
tmc auth doctor

# …or no key at all
tmc mod list --anon --app 4 -o json

Un Perfil Por Sitio O Clave

--profile nombra uno, tmc auth use cambia el predeterminado, y cada valor guardado tiene su gemelo de entorno — TMC_TOKEN, TMC_KEY_ID, TMC_PRIVATE_KEY_FILE, TMC_BASE_URL, TMC_PROFILE.

Pregunta Qué Puede Hacer De Verdad Una Clave

auth whoami determina los permisos reales de la clave con tres sondas deliberadamente inofensivas: una lectura, una creación que no puede validar y un borrado de una lista de ids vacía. No se crea ni se borra nada; --read-only envía solo la lectura.

Un Doctor Para La Configuración

auth doctor informa de qué backend de firma se está usando, si los permisos de tu archivo de configuración son seguros y si el sitio responde siquiera — las tres cosas que conviene saber antes de depurar un pipeline.

Leer Sin Ninguna Clave

--anon lee el resumen público de siete tipos sin cabecera Authorization — es un endpoint realmente distinto, así que rechaza las escrituras antes de que salga la petición, descarta los filtros que esa superficie no tiene en lugar de dejar que parezca que coincidieron, y nunca se actualiza en silencio a una clave guardada. --set apiPublic=false es la forma de sacar un elemento de ahí.
Relaciones

Cuatro Verbos Que Dicen Lo Que Hacen

El peligroso es set: en esta API un PUT a una relación significa «este es ahora el conjunto completo», así que un PUT con un solo miembro borra todo lo demás del elemento. La CLI mantiene los cuatro separados y avisa antes de enviar el destructivo.

Comando Método Significa
tmc rel add POST Añade estos, deja todo lo demás
tmc rel set PUT Este es ahora el conjunto completo
tmc rel rm DELETE Elimina los que has nombrado
tmc rel clear DELETE Elimínalos todos
relations.sh
# Add two tags. The rest of the item is untouched
tmc tags add mod 5 pvp vanilla

# Upload a screenshot and attach it in one step
tmc media add mod 5 --file shot.png --title Screenshot

# Read one relation back
tmc rel get mod 5 releases

# …and the one that REPLACES the whole gallery
tmc rel set mod 5 media --from-file gallery.json
Automatización

Hecho Para Vivir En CI

Compila tu proyecto, publica una versión y sube sus archivos en cada etiqueta. Las credenciales vienen del entorno, así que no se escribe nada en el disco de un runner.

release.yml
- name: Publish to TMC
  env:
    TMC_TOKEN: ${{ secrets.TMC_TOKEN }}
  run: |
    tmc release publish --mod 42 \
      --version "${GITHUB_REF_NAME#v}" \
      --content-file CHANGELOG.md \
      --file 'dist/*.zip'

# Clean pipes: data on stdout, progress on stderr
tmc mod list --mine --all -o ids | xargs -n1 tmc mod get -o json

Nada Escrito En Un Runner

La credencial sale del entorno, así que no se crea ningún perfil y nada sobrevive al trabajo. Una clave JWT puede seguir siendo un archivo secreto que el runner monta — nosotros solo guardamos su mitad pública.

Códigos De Salida Con Significado

2 uso, 3 autenticación, 4 no encontrado, 5 validación, 6 límite de tasa, 7 servidor, 8 red — para que un pipeline distinga «reintenta esto» de «arregla tu clave».

Nunca Bloqueado Por Una Versión Vieja

Un campo que la herramienta todavía no conoce pasa igualmente con --allow-unknown-fields, y tmc raw envía cualquier petición que quieras.

Probado Contra Lo Real

75 pruebas ejecutan la CLI de verdad contra un simulacro de la API en proceso sobre un socket real — los dos modos de autenticación, la agrupación por lotes, la semántica de relaciones y la ruta de reintentos.

Las Claves Están En Cuenta → Claves De API

Una clave es gratis, se crea en un momento y lleva permisos de lectura / escritura / borrado, caducidad, listas de IP permitidas y su propio límite de tasa — así que una clave que le des a un servidor de compilación puede hacer exactamente una cosa. Cada comando, opción y código de salida está documentado en la documentación.

Una clave es útil hoy — la API está en marcha y la documentación está escrita. tmc en sí sigue sin publicarse: todavía no hay paquete en PyPI ni repositorio público, así que es una copia del código fuente hasta que eso cambie.