--- title: "Kotlin Script (.kts): Automação e Scripts sem Compilar | Kotlin Brasil" url: "https://kotlin.dev.br/blog/kotlin-script-kts-automacao-2026/" markdown_url: "https://kotlin.dev.br/blog/kotlin-script-kts-automacao-2026.MD" description: "Aprenda a usar Kotlin Script (.main.kts) para automação, tarefas DevOps e scripts do dia a dia. Exemplos com dependências, comparação com Bash e Python." date: "2026-04-24" author: "Karina Melo" --- # Kotlin Script (.kts): Automação e Scripts sem Compilar | Kotlin Brasil Aprenda a usar Kotlin Script (.main.kts) para automação, tarefas DevOps e scripts do dia a dia. Exemplos com dependências, comparação com Bash e Python. Quando alguém fala em Kotlin, a primeira associação geralmente é Android ou backend com [Spring Boot](/blog/kotlin-spring-boot/). Mas existe um lado menos explorado da linguagem que pode mudar sua produtividade no dia a dia: **Kotlin Script**. Com arquivos `.main.kts`, você escreve e executa scripts diretamente — sem compilar, sem criar projeto, sem `main()`. Basta um arquivo e o comando `kotlin` no terminal. Neste artigo, vamos explorar como usar Kotlin como linguagem de scripting para automação, tarefas DevOps, processamento de dados e tudo mais que você hoje faz com Bash ou Python. Se você já programa em Kotlin, vai aproveitar todo o type safety, null safety e a biblioteca padrão que já conhece — agora em scripts rápidos e descartáveis. ## O que é Kotlin Script? Kotlin Script é a capacidade de executar código Kotlin diretamente, sem precisar de um projeto estruturado com `build.gradle.kts`, sem declarar uma função `main()` e sem etapa explícita de compilação. Você cria um arquivo com extensão `.main.kts`, escreve código top-level e executa com `kotlin script.main.kts`. O formato `.main.kts` é o padrão oficial mantido pela JetBrains. Ele suporta: - Código top-level (sem precisar de classes ou funções `main`) - Importação de dependências Maven via anotações `@file:DependsOn` - Resolução automática de repositórios com `@file:Repository` - Imports implícitos da biblioteca padrão do Kotlin - Suporte nativo no IntelliJ IDEA com autocomplete e highlighting Se você já trabalha com [Gradle Kotlin DSL](/tutoriais/kotlin-gradle-tutorial/), já usa Kotlin Script sem perceber — os arquivos `build.gradle.kts` e `settings.gradle.kts` são scripts Kotlin. ## Primeiros passos ### Pré-requisitos Você precisa do Kotlin instalado na máquina. Se já tem o IntelliJ IDEA, o compilador vem junto. Caso contrário, instale via SDKMAN: ```kotlin // Terminal // sdk install kotlin ``` Ou via Homebrew no macOS: ```kotlin // Terminal // brew install kotlin ``` Verifique a instalação: ```kotlin // Terminal // kotlin -version // Kotlin version 2.3.20-release (JRE 21.0.3+9) ``` Se você quer um guia completo de setup, confira [como instalar Kotlin](/perguntas/como-instalar-kotlin/). ### Seu primeiro script Crie um arquivo chamado `ola.main.kts`: ```kotlin // ola.main.kts val nome = "Kotlin Brasil" val versao = KotlinVersion.CURRENT println("Olá do $nome!") println("Rodando Kotlin $versao") println("Data: ${java.time.LocalDate.now()}") ``` Execute no terminal: ```kotlin // Terminal // kotlin ola.main.kts // Olá do Kotlin Brasil! // Rodando Kotlin 2.3.20 // Data: 2026-04-24 ``` Nenhum `fun main()`, nenhum `class`, nenhum build. O código roda direto. A primeira execução pode demorar alguns segundos para compilação em cache, mas execuções subsequentes são muito mais rápidas. ## Adicionando dependências externas A feature mais poderosa do `.main.kts` é a capacidade de importar bibliotecas Maven diretamente no script com anotações: ```kotlin // relatorio.main.kts @file:DependsOn("com.squareup.okhttp3:okhttp:4.12.0") @file:DependsOn("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.1") import okhttp3.OkHttpClient import okhttp3.Request import kotlinx.serialization.json.* val client = OkHttpClient() val request = Request.Builder() .url("https://api.github.com/repos/JetBrains/kotlin") .build() val response = client.newCall(request).execute() val json = Json.parseToJsonElement(response.body!!.string()) val stars = json.jsonObject["stargazers_count"] val forks = json.jsonObject["forks_count"] val language = json.jsonObject["language"] println("Repositório Kotlin no GitHub:") println(" Estrelas: $stars") println(" Forks: $forks") println(" Linguagem: $language") ``` As dependências são baixadas automaticamente do Maven Central na primeira execução e cacheadas para as próximas. Se precisar de um repositório diferente, use `@file:Repository`: ```kotlin @file:Repository("https://jitpack.io") @file:DependsOn("com.github.usuario:biblioteca:1.0.0") ``` Isso é semelhante ao que fazemos no [Gradle Version Catalog](/blog/gradle-version-catalog-kotlin-2026/), mas para scripts avulsos. ## Casos de uso práticos ### Automação de deploy Um script para verificar o status de containers Docker e notificar via webhook: ```kotlin // check-deploy.main.kts @file:DependsOn("com.squareup.okhttp3:okhttp:4.12.0") import okhttp3.OkHttpClient import okhttp3.Request import okhttp3.RequestBody.Companion.toRequestBody import okhttp3.MediaType.Companion.toMediaType data class Container(val nome: String, val status: String, val uptime: String) fun verificarContainers(): List { val process = ProcessBuilder("docker", "ps", "--format", "{{.Names}}|{{.Status}}") .redirectErrorStream(true) .start() return process.inputStream.bufferedReader().readLines() .filter { it.isNotBlank() } .map { linha -> val partes = linha.split("|") Container( nome = partes[0], status = if (partes[1].startsWith("Up")) "running" else "stopped", uptime = partes[1] ) } } val containers = verificarContainers() val parados = containers.filter { it.status == "stopped" } if (parados.isNotEmpty()) { println("ALERTA: ${parados.size} container(s) parado(s):") parados.forEach { println(" - ${it.nome}: ${it.uptime}") } } else { println("Todos os ${containers.size} containers estão rodando.") } ``` Se você trabalha com [Kubernetes](/blog/kotlin-kubernetes/) ou [Docker](/guias/guia-kotlin-docker/), scripts como esse substituem Bash com a vantagem de type safety e tratamento de erros robusto. ### Processamento de CSV Ler um CSV de funcionários e gerar estatísticas — algo que muitos fazem em Python: ```kotlin // analise-salarios.main.kts import java.io.File data class Funcionario( val nome: String, val departamento: String, val salario: Double, val experiencia: Int ) val funcionarios = File("funcionarios.csv") .readLines() .drop(1) // pular header .map { linha -> val campos = linha.split(",") Funcionario( nome = campos[0].trim(), departamento = campos[1].trim(), salario = campos[2].trim().toDouble(), experiencia = campos[3].trim().toInt() ) } println("Total de funcionários: ${funcionarios.size}") println("Salário médio: R$ ${"%.2f".format(funcionarios.map { it.salario }.average())}") println() // Agrupamento por departamento funcionarios.groupBy { it.departamento } .toSortedMap() .forEach { (depto, funcs) -> val media = funcs.map { it.salario }.average() println("$depto: ${funcs.size} pessoas, média R$ ${"%.2f".format(media)}") } println() // Top 5 salários println("Top 5 salários:") funcionarios.sortedByDescending { it.salario } .take(5) .forEachIndexed { i, f -> println(" ${i + 1}. ${f.nome} (${f.departamento}): R$ ${"%.2f".format(f.salario)}") } ``` Perceba como as [collections do Kotlin](/glossario/collections/) — `groupBy`, `sortedByDescending`, `map`, `average` — tornam o processamento de dados expressivo e conciso, comparável ao Python. ### Geração de código e scaffolding Criar arquivos de projeto automaticamente: ```kotlin // scaffold.main.kts import java.io.File val pacote = args.getOrElse(0) { "com.exemplo" } val nome = args.getOrElse(1) { "MeuProjeto" } val diretorios = listOf( "src/main/kotlin/${pacote.replace('.', '/')}", "src/main/resources", "src/test/kotlin/${pacote.replace('.', '/')}", "src/test/resources" ) diretorios.forEach { File(it).mkdirs() } File("src/main/kotlin/${pacote.replace('.', '/')}/Application.kt").writeText(""" package $pacote fun main() { println("$nome iniciado com sucesso!") } """.trimIndent()) File("build.gradle.kts").writeText(""" plugins { kotlin("jvm") version "2.3.20" application } group = "$pacote" version = "1.0.0" application { mainClass.set("$pacote.ApplicationKt") } repositories { mavenCentral() } dependencies { testImplementation(kotlin("test")) } """.trimIndent()) println("Projeto '$nome' criado com sucesso!") println("Pacote: $pacote") println("Diretórios criados: ${diretorios.size}") ``` Execute com: `kotlin scaffold.main.kts com.kotlinbrasil MeuApp` ## Kotlin Script vs Bash vs Python Uma comparação honesta para decidir quando usar cada um: ### Kotlin Script vence quando - Você já é dev Kotlin e quer aproveitar o conhecimento existente - O script precisa de type safety e tratamento de [null safety](/glossario/nullable/) robusto - Você quer usar bibliotecas Java/Kotlin existentes (OkHttp, kotlinx-serialization, etc.) - O script pode crescer e eventualmente virar um projeto — a migração é trivial - Integração com [CI/CD](/blog/kotlin-devops-ci-cd/) onde o ambiente já tem Kotlin ### Bash vence quando - São operações simples de sistema de arquivos (mover, copiar, renomear) - Pipes e redirecionamento são a ferramenta certa - O ambiente pode não ter JVM instalada - O script tem menos de 20 linhas ### Python vence quando - Data science pesado com NumPy, Pandas, matplotlib - O time não conhece Kotlin - Prototipagem rápida de ML (embora o [Kotlin Notebook](/blog/kotlin-notebook-data-science-2026/) esteja fechando essa lacuna) Se você quer uma comparação mais profunda entre Kotlin e Python como linguagens, confira nosso artigo [Kotlin vs Python](/blog/kotlin-vs-python/). Para automação e scripting, Python continua sendo referência, mas o Kotlin Script brilha quando você quer type safety e acesso ao ecossistema JVM. Já para automação de infra e CLIs performáticas, Go é uma alternativa forte com binários estáticos e compilação rápida. ## Dicas avançadas ### Shebang para execução direta No Linux e macOS, adicione um shebang no início do script para executá-lo diretamente: ```kotlin #!/usr/bin/env kotlin // meu-script.main.kts println("Executando diretamente!") println("Argumentos: ${args.joinToString()}") ``` Depois torne executável com `chmod +x meu-script.main.kts` e rode com `./meu-script.main.kts`. ### IDE support no IntelliJ O IntelliJ IDEA reconhece arquivos `.main.kts` nativamente. Você ganha: - Autocomplete completo, incluindo dependências declaradas com `@file:DependsOn` - Highlighting de sintaxe e erros em tempo real - Botão de run direto no editor - Navegação para código-fonte das dependências Isso é uma vantagem significativa sobre Bash, onde o suporte de IDE é limitado. Se você usa [VS Code](/blog/kotlin-vscode-converter-java-kotlin-2026/), o suporte a `.main.kts` é mais básico, mas funcional. ### Cache e performance A primeira execução de um script `.main.kts` é mais lenta porque o Kotlin precisa compilar e resolver dependências. Execuções subsequentes usam cache e são significativamente mais rápidas. Se performance de cold start é crítica, considere compilar o script para um JAR com `kotlinc -script script.main.kts`. Para scripts que rodam em [pipelines de CI/CD](/blog/kotlin-github-actions/), o cache de dependências Maven ajuda bastante. ## Limitações e futuro Algumas limitações atuais do Kotlin Script: 1. **Cold start** — a primeira execução compila o script, o que leva alguns segundos. Para scripts que rodam uma vez e somem (como em cron jobs), isso pode importar 2. **Sem suporte a Kotlin Multiplatform** — scripts rodam apenas na JVM, não em Native ou WASM 3. **Debugging limitado** — embora o IntelliJ suporte breakpoints em `.main.kts`, a experiência não é tão polida quanto em projetos estruturados 4. **kscript em manutenção** — a ferramenta [kscript](https://github.com/kscripting/kscript), que adicionava features como cache agressivo e execução em background, não recebe atualizações desde 2023. A recomendação atual é usar `.main.kts` nativo ou [JBang](https://www.jbang.dev/) como alternativa A JetBrains confirmou que continuará investindo em `.main.kts` como o formato oficial de scripting. Melhorias em IDE support e performance de cold start estão no roadmap para versões futuras do Kotlin. ## Quando migrar um script para um projeto Se seu script `.main.kts` começa a crescer além de 200-300 linhas, considere migrar para um projeto Kotlin estruturado. Sinais de que é hora de migrar: - Você precisa de múltiplos arquivos ou módulos - O script precisa de testes automatizados — veja nosso post sobre [Power-Assert](/blog/kotlin-power-assert-plugin-testes-2026/) para testes sem dependências externas - Distribuição para outros devs que podem não ter o Kotlin instalado - Performance de startup importa e você quer compilar para um fat JAR A migração é simples: o código Kotlin é o mesmo, você só precisa mover de top-level para dentro de funções e adicionar um `build.gradle.kts`. Toda a lógica, [extension functions](/glossario/extension-function/) e imports continuam funcionando. ## Perguntas frequentes ### Posso usar coroutines em Kotlin Script? Sim. Adicione `@file:DependsOn("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")` e use [coroutines](/glossario/coroutine/) normalmente. Você vai precisar de `runBlocking` como entry point, já que o script roda em contexto top-level. ### Kotlin Script funciona no Windows? Sim. Desde que o Kotlin esteja instalado e no PATH, funciona em Windows, Linux e macOS. O shebang (`#!/usr/bin/env kotlin`) funciona apenas em sistemas Unix. ### Posso acessar argumentos da linha de comando? Sim. A variável `args` (do tipo `Array`) está disponível automaticamente em scripts `.main.kts`, similar ao `args` da função `main()` em projetos Kotlin convencionais. ### Como usar Kotlin Script em pipelines de CI/CD? Instale o Kotlin no runner de CI e execute com `kotlin script.main.kts`. Em [GitHub Actions](/blog/kotlin-github-actions/), você pode usar a action `setup-kotlin` para configurar o ambiente. Para [Gitea Actions](/blog/kotlin-devops-ci-cd/), o setup é similar.