Linha de comandos e automação

O MDM pode ser controlado sem a sua janela de três formas:

• A linha de comandos da própria aplicação, os mesmos parâmetros do IDM: entregar uma transferência à aplicação em execução a partir de um script, um ficheiro batch ou outro programa.
• misterdownloadmanager-cli, uma ferramenta de linha de comandos separada: transferir ficheiros, vídeos e torrents num terminal, com progresso, sem a aplicação.
• A API de automação: outros programas listam as transferências da aplicação em execução (como JSON) e pausam, iniciam, removem ou apagam-nas, através de um canal local protegido por token. Os assistentes de IA usam-no através do servidor MCP do MDM: consulte Assistentes de IA.

Os exemplos usam caminhos do Windows; no macOS e Linux os programas têm os mesmos nomes sem .exe.

A linha de comandos da aplicação

misterdownloadmanager.exe /d URL [/p folder] [/f name] [/a] [/n] [/s]

Os parâmetros podem começar com / ou -, em qualquer caso. Se o MDM estiver em execução, o comando vai para ele; se não, o MDM inicia e executa-o. Por exemplo:

misterdownloadmanager.exe /d https://example.com/files/report.pdf /p D:\Reports /n
misterdownloadmanager.exe /d https://example.com/big.iso /a
misterdownloadmanager.exe /s

misterdownloadmanager-cli

Vem com cada transferência do MDM, ao lado da aplicação (o instalador coloca-o na pasta do MDM). Funciona por si só: a aplicação não precisa de estar em execução, exceto para status e api.

misterdownloadmanager-cli help <command>mostra todas as opções. Um comando que falha (a aplicação não está em execução, responde com um erro, uma transferência falha) termina com o código 1. Por exemplo:

misterdownloadmanager-cli get https://example.com/big.iso -o D:\Downloads -c 16 --checksum sha256:9f86d0…
misterdownloadmanager-cli video-get "https://www.youtube.com/watch?v=aqz-KE-bpKQ" -f "b[height=720]"
misterdownloadmanager-cli torrent-get "magnet:?xt=urn:btih:…" --files 0

JSON para scripts e programas

Com --json (antes ou depois do comando), cada comando imprime JSON em vez de texto, um objeto por linha, para scripts e agentes de IA lerem:

Os tamanhos são em bytes (null enquanto desconhecido), as velocidades em bytes por segundo. Uma falha imprime {"error": "…"} e termina com o código 1. Por exemplo:

misterdownloadmanager-cli --json get https://example.com/big.iso -o D:\Downloads
{"event":"progress","downloaded":4194304,"size":1073741824,"speed":52428800,"connections":8,"segments":8}
…
{"event":"done","path":"D:\\Downloads\\big.iso","size":1073741824,"seconds":20.4}

A API de automatização

Outros programas podem perguntar à aplicação em execução o que está a transferir e interromper, iniciar, remover ou apagar transferências. A API está desativada por predefinição; ative-a com misterdownloadmanager-cli api on (e desative-a com api off).

Como um programa comunica com o MDM

1. Enquanto está em execução, o MDM escuta numa porta de 127.0.0.1 (apenas neste computador) e escreve a porta e um token secreto para ipc.json na sua pasta de dados: - Windows: %APPDATA%\misterdownloadmanager\ipc.json - macOS: ~/Library/Application Support/misterdownloadmanager/ipc.json - Linux: ~/.local/share/misterdownloadmanager/ipc.json - Uma cópia portátil: data\ipc.json ao lado do programa.

O token muda a cada início; apenas programas que podem ler a sua pasta de dados (a sua) podem usá-lo. 2. Conecte-se a essa porta e envie uma linha de JSON: o token e os campos do comando, por exemplo {"token": "<token>", "query": "list"}. 3. O MDM responde com uma linha: ok para um comando, ou um objeto JSON para uma pergunta.

O que ele entende

Uma pergunta ou ação desconhecida é respondida com {"error": "…"}, assim como uma pergunta enquanto a API está desativada (então com "code": "api-off", para os programas verificarem: o texto do erro pode mudar). Um token errado é respondido com denied.

Cada pedido e resposta é descrito, campo a campo, num JSON Schema: automation-api.schema.json (também em https://misterdownloadmanager.com/automation-api.schema.json). É feito a partir do código com que a aplicação responde, para que se mantenha exato; os programas podem verificar o que enviam e leem em relação a ele, ou gerar os seus tipos a partir dele.

Exemplos

PowerShell (Windows):

$ep = Get-Content "$env:APPDATA\misterdownloadmanager\ipc.json" | ConvertFrom-Json
$client = New-Object Net.Sockets.TcpClient("127.0.0.1", $ep.port)
$stream = $client.GetStream()
$writer = New-Object IO.StreamWriter($stream); $reader = New-Object IO.StreamReader($stream)
$writer.WriteLine((@{ token = $ep.token; query = "list" } | ConvertTo-Json -Compress))
$writer.Flush()
$reader.ReadLine() | ConvertFrom-Json | Select-Object -ExpandProperty downloads | Format-Table file, status, downloaded, size
$client.Close()

Python:

import json, os, socket

ipc = os.path.join(os.environ["APPDATA"], "misterdownloadmanager", "ipc.json")  # see above elsewhere
ep = json.load(open(ipc))
with socket.create_connection(("127.0.0.1", ep["port"])) as s:
    s.sendall((json.dumps({"token": ep["token"], "query": "list"}) + "\n").encode())
    answer = json.loads(s.makefile().readline())
for d in answer["downloads"]:
    print(d["file"], d["status"], d["downloaded"], d["size"])

Para adicionar uma transferência, envie {"token": "…", "url": "https://example.com/a.zip", "silent": true}.