tmc-cli - The Modding Community

Open source

tmc-cli is een opdrachtregelclient voor onze publieke content-API. Hij maakt, bewerkt en verwijdert je assets, mods, servers, artikelen, communities, collecties en groepen, en omdat de API daar in de praktijk voor gebruikt wordt, uploadt hij bestanden en publiceert hij releases in één commando.

Python 3.11+Nul afhankelijkhedenMIT-licentie

Installeer vanuit een kloon. tmc-cli staat nog niet op PyPI, dus pip installeert het vanuit de openbare repository. De drie stappen staan verderop.

$ tmc auth whoamiprofile    defaultsite       https://moddingcommunity.comauthMode   tokentoken      tmc_ab…9fcanRead    truecanWrite   truecanDelete  false

Eén pakket uit de standaardbibliotheek: er valt niets te bouwen of op te lossen. Het staat niet op PyPI en wordt dus vanuit een kloon geïnstalleerd. Elk commando, elke vlag en elke exitcode staat in de documentatie.

Installatie

Drie stappen, geen pakketindex

tmc-cli staat niet op PyPI. Het wordt vanuit een kloon van de openbare repository geïnstalleerd, vraagt Python 3.11 of nieuwer en haalt geen andere pakketten binnen.

  1. 1

    Kloon het

    Haal de broncode op. Er wordt niets gebouwd of gecompileerd.

    git clone https://github.com/modcommunity/tmc-cli.git && cd tmc-cli
  2. 2

    Installeer het

    pip zet het commando tmc in uw PATH. De extra is optioneel: met cryptography geïnstalleerd gaat het ondertekenen sneller. Het pakket heet tmc-cli, maar het commando dat u typt is tmc.

    pip install .
  3. 3

    Log in

    Maak een sleutel onder Account, API-sleutels en log in. Of lees openbare items zonder sleutel met --anon.

    tmc auth login --token tmc_xxxxxxxxxxxx
Commando's

Eén tool, zes hoeken van de API

Commandonamen zijn precies wat er getypt wordt. Draai tmc --help voor de volledige lijst.

Inhoud

List, get, create, update en delete voor elk inhoudstype.

assetmodservercommunityarticlecollectiongroup

Rond een item

Tags, media, links, relaties, reacties en recensies, elk beheerd zonder het item opnieuw te sturen.

tagtagsmedialinksrelcommentreview

Bestanden en releases

Upload bestanden, maak een release en koppel ze met één commando.

filerelease

Uw account

Favorieten, vrienden, groepen, installaties en abonnementen.

authaccountfavoritefriendspartyinstallssubscriptions

De site

Status van de netwerkmonitor, statistieken, filters, de catalogus, meldingen en play.

defconstatsfiltercatalogreportplay

De tool zelf

Het schema waartegen gecontroleerd wordt, aanvullingen voor uw shell en raw voor elk verzoek.

schemacontractcompletionopenraw

Releases

Releases Met Één Opdracht

Een release uitbrengen via de kale API is vier verzoeken in een bepaalde volgorde: de bestanden uploaden, hun ids verzamelen, de bestaande releaseverzameling lezen en dan de nieuwe terugschrijven zonder de andere te verstoren. release publish is precies die reeks.

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

Opnieuw Uitvoeren Werkt Bij

Dezelfde --version twee keer werkt die release bij en voegt de nieuwe bestanden aan de verzameling toe. Je andere releases worden nooit aangeraakt, en een verborgen release blijft verborgen.

Globs, Gebundeld

Geef --file 'dist/*.zip' mee en zoveel bestanden als je hebt; de limiet van twintig uploads per verzoek wordt voor je afgehandeld.

Grote Bestanden Streamen

Een upload van 1 GB wordt in stukken van schijf gelezen, niet in het geheugen. Alles boven de groottelimiet van je sleutel wordt gemeld voordat het wordt verstuurd.
Wat Hij Doet

Wat De CLI Kan

Eén opdracht voor alles wat je in de browser zou doen, plus een paar dingen die je niet met de hand wilt doen: bulkbewerkingen, pipelines en releases via scripts.

Helemaal Geen Afhankelijkheden

Python 3.11+ en de standaardbibliotheek. Zet hem op een buildmachine of een gameserver zonder pakketindex en hij draait. cryptography wordt gebruikt voor ondertekenen als het toevallig geïnstalleerd is, en anders een meegeleverde RFC 8032-implementatie, dezelfde handtekeningen hoe dan ook.

Beide Authenticatiemodi

Bearer-tmc_-sleutels, of Ed25519-ondertekende assertions waarbij jij de privésleutel houdt en wij alleen de publieke helft bewaren.

Eén Grammatica Voor Elk Type

Dezelfde vijf werkwoorden, list, get, create, update, delete, voor elk inhoudstype. tmc content <type> is de uniforme vorm en de enige weg naar de losstaande typen release en media.

Relaties Zonder Alles Opnieuw Te Sturen

Tags, media, releases, links, bronnen en collectie-items worden apart beheerd, dus één screenshot toevoegen betekent niet het hele item herschrijven.

In Bulk, Binnen Elke Limiet

Maak of bewerk vanuit een JSON-bestand van willekeurige lengte. Elke serverlimiet, 25 per schrijfactie, 100 per verwijdering, 200 relatieleden, 500 sleutels bij het verwijderen van een relatie, 20 uploaddelen, wordt voor je gebundeld, en bij een gedeeltelijke fout wordt het element genoemd dat misging zodat je verder kunt in plaats van opnieuw te beginnen.

Typefouten Lokaal Opgevangen

Veldnamen worden gecontroleerd tegen een lokale kopie van de API-schema's, mét de bijna-treffer: 'mod' heeft geen veld 'tgs'. Bedoelde je 'tags'? tmc schema mod drukt de veldlijst af waartegen wordt gecontroleerd.

Gemaakt Voor Pipes

Zeven uitvoerformaten, table, json, jsonl, csv, tsv, yaml, ids, met --field om alleen de gewenste kolommen over te houden. Data op stdout, voortgang op stderr, en tmc completion bash|zsh|fish voor de shell waarin je zit.

Rate Limits Afgehandeld

Een 429 wordt precies zolang uitgezeten als de API vraagt, tot --retry-wait-max, en daarna krijg je te horen hoe lang er nog rest in plaats van dat een build blijft hangen. Backoff geldt alleen voor idempotente methodes, een POST wordt nooit stilletjes herhaald.
Inloggegevens

Sleutels, Profielen En De Publieke Helft

Log één keer in en de gegevens worden opgeslagen in ~/.config/tmc/config.json met modus 0600, of geef ze mee via de omgeving en er wordt helemaal niets naar schijf geschreven. Eén profiel per site of per sleutel, en --anon voor de helft van de API die überhaupt geen sleutel nodig heeft.

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

Een Profiel Per Site Of Sleutel

--profile benoemt er een, tmc auth use wisselt de standaard, en elke opgeslagen waarde heeft een omgevingsequivalent, TMC_TOKEN, TMC_KEY_ID, TMC_PRIVATE_KEY_FILE, TMC_BASE_URL, TMC_PROFILE.

Vraag Wat Een Sleutel Echt Mag

auth whoami stelt de werkelijke rechten van de sleutel vast met drie bewust onschadelijke proeven, een leesactie, een aanmaak die niet kan valideren, en een verwijdering van een lege lijst met ids. Er wordt niets gemaakt of verwijderd; --read-only stuurt alleen de leesactie.

Een Dokter Voor De Opzet

auth doctor meldt welke ondertekeningsbackend in gebruik is, of de rechten van je configuratiebestand veilig zijn en of de site überhaupt antwoordt, de drie dingen die je wilt weten voordat je een pipeline gaat debuggen.

Lezen Zonder Enige Sleutel

--anon leest de publieke samenvatting van zeven typen zonder Authorization-header, een werkelijk ander endpoint, dus het weigert schrijfacties voordat het verzoek de deur uit is, laat de filters vallen die dat oppervlak niet heeft in plaats van te doen alsof ze iets matchten, en schakelt nooit stiekem over op een opgeslagen sleutel. --set apiPublic=false is hoe een item eruit vertrekt.
Relaties

Vier Werkwoorden Die Zeggen Wat Ze Doen

De gevaarlijke is set: op deze API betekent een PUT op een relatie „dit is nu de volledige verzameling”, dus een PUT met één lid verwijdert al het andere op het item. De CLI houdt de vier uit elkaar en waarschuwt voordat hij de destructieve verstuurt.

Commando Methode Betekent
tmc rel add POST Voeg deze toe, laat de rest staan
tmc rel set PUT Dit is nu de volledige verzameling
tmc rel rm DELETE Haal degene weg die je noemde
tmc rel clear DELETE Haal ze allemaal weg
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
Automatisering

Gebruik Hem In CI

Bouw je project, breng een release uit en upload de bestanden bij elke tag. Inloggegevens komen uit de omgeving, dus er wordt niets naar de schijf van een runner geschreven.

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

Niets Naar Een Runner Geschreven

De inloggegevens komen uit de omgeving, dus er wordt geen profiel aangemaakt en niets overleeft de job. Een JWT-sleutel mag een geheim bestand blijven dat de runner aankoppelt, wij houden altijd alleen de publieke helft.

Exitcodes Die Iets Betekenen

2 gebruik, 3 authenticatie, 4 niet gevonden, 5 validatie, 6 rate limit, 7 server, 8 netwerk, zodat een pipeline „opnieuw proberen” kan onderscheiden van „repareer je sleutel”.

Nooit Geblokkeerd Door Een Verouderde Build

Een veld dat het gereedschap nog niet kent gaat er met --allow-unknown-fields alsnog doorheen, en tmc raw stuurt werkelijk elk verzoek.

Getest Tegen Het Echte Werk

203 tests draaien de echte CLI tegen een in-process nabootsing van de API over een echte socket, beide authenticatiemodi, het bundelen, de relatiesemantiek en het herhaalpad.

Sleutels Vind Je Onder Account → API-Sleutels

Een sleutel is gratis, is zo gemaakt en draagt lees-/schrijf-/verwijderrechten, een vervaldatum, IP-toegangslijsten en een eigen rate limit, dus een sleutel die je aan een buildserver geeft kan precies één ding. Elk commando, elke vlag en elke exitcode staat in de documentatie.

Een sleutel is vandaag al nuttig: de API is live en de documentatie is geschreven. tmc-cli is open source en wordt vanuit een kloon van de repository geïnstalleerd. Het staat nog niet op PyPI.