CINXE.COM

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="x-ua-compatible" content="ie=edge"><meta name="viewport" content="width=device-width,initial-scale=1"><script>!function(e,t,a,n){e[n]=e[n]||[],e[n].push({"gtm.start":(new Date).getTime(),event:"gtm.js"});var g=t.getElementsByTagName(a)[0],m=t.createElement(a);m.async=!0,m.src="https://www.googletagmanager.com/gtm.js?id=GTM-5VSZM5J",g.parentNode.insertBefore(m,g)}(window,document,"script","dataLayer")</script><meta name="description" content="Explore a command-line application written in Dart."><title>Write command-line apps | Dart</title><link rel="icon" sizes="64x64" href="/assets/img/logo/dart-64.png" eleventy:ignore><link href="/assets/img/touch-icon-iphone.png" rel="apple-touch-icon" eleventy:ignore><link href="/assets/img/touch-icon-ipad.png" rel="apple-touch-icon" sizes="152x152" eleventy:ignore><link href="/assets/img/touch-icon-iphone-retina.png" rel="apple-touch-icon" sizes="180x180" eleventy:ignore><link href="/assets/img/touch-icon-ipad-retina.png" rel="apple-touch-icon" sizes="167x167" eleventy:ignore><meta name="twitter:card" content="summary"><meta name="twitter:site" content="@dart_lang"><meta name="twitter:title" content="Write command-line apps"><meta name="twitter:description" content="Explore a command-line application written in Dart."><meta property="og:title" content="Write command-line apps"><meta property="og:description" content="Explore a command-line application written in Dart."><meta property="og:url" content="/tutorials/server/cmdline/"><meta property="og:image" content="/assets/img/logo/dart-logo-for-shares.png?2" eleventy:ignore><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Google+Sans:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Display:wght@400&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Text:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0" rel="stylesheet"><link rel="stylesheet" href="/assets/css/main.css"><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min.js" integrity="sha512-3gJwYpMe3QewGELv8k/BX9vcqhryRdzRMxVfq6ngyWXwo03GFEzjsUm8Q7RZcHPHksttq7/GFoxjCVUjkjvPdw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/4.6.2/js/bootstrap.min.js" integrity="sha384-+sLIOodYLS7CIrQpBjl+C7nPvqq+FbNUBDunl/OZv93DB7Ln/533i8e/mZXLi/P+" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/js-cookie/3.0.5/js.cookie.min.js" integrity="sha512-nlp9/l96/EpjYBx7EP7pGASVXNe80hGhYAUrjeXnu/fyF5Py0/RXav4BBNs7n5Hx1WFhOEOWSAVjGeC3oKxDVQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="/assets/js/os-tabs.js"></script><script src="/assets/js/utilities.js"></script><script src="/assets/js/main.js"></script><script>!function(e,a,t,n,c,o,s){e.GoogleAnalyticsObject=c,e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},e[c].l=1*new Date,o=a.createElement(t),s=a.getElementsByTagName(t)[0],o.async=1,o.src="//www.google-analytics.com/analytics.js",s.parentNode.insertBefore(o,s)}(window,document,"script",0,"ga"),ga("create","UA-26406144-4","auto"),ga("send","pageview")</script></head><body class="default.html show_banner"><a id="skip" href="#site-content-title">Skip to main content</a><section id="cookie-notice"><div class="container">dart.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. <a href="https://policies.google.com/technologies/cookies" target="_blank" rel="noopener">Learn more</a>.<button id="cookie-consent" class="btn btn-primary">OK, got it</button></div></section><noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5VSZM5J" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript><header id="page-header" class="site-header"><nav id="mainnav" class="site-header"><div id="menu-toggle">menu</div><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart"></a><ul class="navbar"><li><a href="/overview" class="nav-link">Overview</a></li><li class="mainnav__get-started"><a href="/guides" class="nav-link active">Docs</a></li><li><a href="/community" class="nav-link">Community</a></li><li><a href="/#try-dart" class="nav-link">Try Dart</a></li><li><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="searchfield"><form action="/search" class="site-header__search form-inline" id="cse-search-box"><input type="hidden" name="cx" value="011220921317074318178:_yy-tmb5t_i"> <input type="hidden" name="ie" value="UTF-8"> <input type="hidden" name="hl" value="en"> <input class="site-header__searchfield form-control search-field" type="search" name="q" id="search-main" autocomplete="off" placeholder="Search" aria-label="Search"></form></li></ul></nav></header><div class="banner">Announcing Dart 3.5 and an updated Dart roadmap! <a href="https://medium.com/dartlang/dart-3-5-6ca36259fa2f" target="_blank">Learn more</a></div><div id="sidenav"><form action="/search/" class="site-header__search form-inline"><input class="site-header__searchfield form-control search-field" type="search" name="q" id="search-side" autocomplete="off" placeholder="Search" aria-label="Search"></form><div class="site-sidebar"><ul class="navbar-nav"><li class="nav-item"><a href="/overview" class="nav-link">Overview</a></li><li class="nav-item"><a href="/community" class="nav-link">Community</a></li><li class="nav-item"><a href="https://dartpad.dev" class="nav-link">Try Dart</a></li><li class="nav-item"><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="nav-item"><a href="/guides" class="nav-link">Docs</a></li><li aria-hidden="true"><div class="sidebar-primary-divider"></div></li></ul><ul class="nav flex-column"><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-1" role="button" aria-expanded="false" aria-controls="sidenav-1">Language</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1"><li class="nav-item"><a class="nav-link" href="/language">Introduction</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-2" href="#sidenav-1-2" role="button" aria-expanded="false" aria-controls="sidenav-1-2">Syntax basics</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-2"><li class="nav-item"><a class="nav-link" href="/language/variables">Variables</a></li><li class="nav-item"><a class="nav-link" href="/language/operators">Operators</a></li><li class="nav-item"><a class="nav-link" href="/language/comments">Comments</a></li><li class="nav-item"><a class="nav-link" href="/language/metadata">Metadata</a></li><li class="nav-item"><a class="nav-link" href="/language/libraries">Libraries & imports</a></li><li class="nav-item"><a class="nav-link" href="/language/keywords">Keywords</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-3" href="#sidenav-1-3" role="button" aria-expanded="false" aria-controls="sidenav-1-3">Types</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-3"><li class="nav-item"><a class="nav-link" href="/language/built-in-types">Built-in types</a></li><li class="nav-item"><a class="nav-link" href="/language/records">Records</a></li><li class="nav-item"><a class="nav-link" href="/language/collections">Collections</a></li><li class="nav-item"><a class="nav-link" href="/language/generics">Generics</a></li><li class="nav-item"><a class="nav-link" href="/language/typedefs">Typedefs</a></li><li class="nav-item"><a class="nav-link" href="/language/type-system">Type system</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-4" href="#sidenav-1-4" role="button" aria-expanded="false" aria-controls="sidenav-1-4">Patterns</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-4"><li class="nav-item"><a class="nav-link" href="/language/patterns">Overview & usage</a></li><li class="nav-item"><a class="nav-link" href="/language/pattern-types">Pattern types</a></li><li class="nav-item"><a class="nav-link" href="https://codelabs.developers.google.com/codelabs/dart-patterns-records" target="_blank" rel="noopener">Applied tutorial</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/language/functions">Functions</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-6" href="#sidenav-1-6" role="button" aria-expanded="false" aria-controls="sidenav-1-6">Control flow</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-6"><li class="nav-item"><a class="nav-link" href="/language/loops">Loops</a></li><li class="nav-item"><a class="nav-link" href="/language/branches">Branches</a></li><li class="nav-item"><a class="nav-link" href="/language/error-handling">Error handling</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-7" href="#sidenav-1-7" role="button" aria-expanded="false" aria-controls="sidenav-1-7">Classes & objects</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-7"><li class="nav-item"><a class="nav-link" href="/language/classes">Classes</a></li><li class="nav-item"><a class="nav-link" href="/language/constructors">Constructors</a></li><li class="nav-item"><a class="nav-link" href="/language/methods">Methods</a></li><li class="nav-item"><a class="nav-link" href="/language/extend">Extend a class</a></li><li class="nav-item"><a class="nav-link" href="/language/mixins">Mixins</a></li><li class="nav-item"><a class="nav-link" href="/language/enums">Enums</a></li><li class="nav-item"><a class="nav-link" href="/language/extension-methods">Extension methods</a></li><li class="nav-item"><a class="nav-link" href="/language/extension-types">Extension types</a></li><li class="nav-item"><a class="nav-link" href="/language/callable-objects">Callable objects</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-8" href="#sidenav-1-8" role="button" aria-expanded="false" aria-controls="sidenav-1-8">Class modifiers</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-8"><li class="nav-item"><a class="nav-link" href="/language/class-modifiers">Overview & usage</a></li><li class="nav-item"><a class="nav-link" href="/language/class-modifiers-for-apis">Class modifiers for API maintainers</a></li><li class="nav-item"><a class="nav-link" href="/language/modifier-reference">Reference</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-9" href="#sidenav-1-9" role="button" aria-expanded="false" aria-controls="sidenav-1-9">Concurrency</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-9"><li class="nav-item"><a class="nav-link" href="/language/concurrency">Overview</a></li><li class="nav-item"><a class="nav-link" href="/language/async">Asynchronous support</a></li><li class="nav-item"><a class="nav-link" href="/language/isolates">Isolates</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-10" href="#sidenav-1-10" role="button" aria-expanded="false" aria-controls="sidenav-1-10">Null safety</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-10"><li class="nav-item"><a class="nav-link" href="/null-safety">Sound null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/migration-guide">Migrating to null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/understanding-null-safety">Understanding null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/unsound-null-safety">Unsound null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/faq">FAQ</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-2" role="button" aria-expanded="false" aria-controls="sidenav-2">Core libraries</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-2"><li class="nav-item"><a class="nav-link" href="/libraries">Overview</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-core">dart:core</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-async">dart:async</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-math">dart:math</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-convert">dart:convert</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-io">dart:io</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-html">dart:html</a></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/libraries/collections/iterables">Iterable collections</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-2-10" href="#sidenav-2-10" role="button" aria-expanded="false" aria-controls="sidenav-2-10">Asynchronous programming</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-2-10"><li class="nav-item"><a class="nav-link" href="/libraries/async/async-await">Tutorial</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/futures-error-handling">Futures and error handling</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/using-streams">Using streams</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/creating-streams">Creating streams</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-3" role="button" aria-expanded="false" aria-controls="sidenav-3">Effective Dart</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-3"><li class="nav-item"><a class="nav-link" href="/effective-dart">Overview</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/style">Style</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/documentation">Documentation</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/usage">Usage</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/design">Design</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-4" role="button" aria-expanded="false" aria-controls="sidenav-4">Packages</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-4"><li class="nav-item"><a class="nav-link" href="/tools/pub/packages">How to use packages</a></li><li class="nav-item"><a class="nav-link" href="/resources/useful-packages">Commonly used packages</a></li><li class="nav-item"><a class="nav-link" href="/guides/libraries/create-packages">Creating packages</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/publishing">Publishing packages</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/writing-package-pages">Writing package pages</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-4-6" href="#sidenav-4-6" role="button" aria-expanded="false" aria-controls="sidenav-4-6">Package reference</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-4-6"><li class="nav-item"><a class="nav-link" href="/tools/pub/dependencies">Dependencies</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/glossary">Glossary</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/package-layout">Package layout conventions</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/environment-variables">Pub environment variables</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/pubspec">Pubspec file</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/troubleshoot">Troubleshooting pub</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/verified-publishers">Verified publishers</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/security-advisories">Security advisories</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/versioning">Versioning</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/custom-package-repositories">Custom package repositories</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/guides/libraries/private-files">What not to commit</a></li></ul></li><li class="nav-item"><a class="nav-link active collapsible" data-toggle="collapse" href="#sidenav-5" role="button" aria-expanded="true" aria-controls="sidenav-5">Development</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-5"><li class="nav-item"><a class="nav-link" href="/guides/json">JSON</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/numbers">Number representation</a></li><li class="nav-item"><a class="nav-link" href="/resources/google-apis">Google APIs</a></li><li class="nav-item"><a class="nav-link" href="/multiplatform-apps">Multi-platform apps</a></li><li class="nav-item"><a class="nav-link active collapsible" data-toggle="collapse" data-target="#sidenav-5-5" href="#sidenav-5-5" role="button" aria-expanded="true" aria-controls="sidenav-5-5">Command-line & server apps</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-5-5"><li class="nav-item"><a class="nav-link" href="/server">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/get-started">Get started</a></li><li class="nav-item"><a class="nav-link active" href="/tutorials/server/cmdline">Write command-line apps</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/fetch-data">Fetch data from the internet</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/httpserver">Write HTTP servers</a></li><li class="nav-item"><a class="nav-link" href="/server/libraries">Libraries & packages</a></li><li class="nav-item"><a class="nav-link" href="/server/google-cloud">Google Cloud</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-5-6" href="#sidenav-5-6" role="button" aria-expanded="false" aria-controls="sidenav-5-6">Web apps</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5-6"><li class="nav-item"><a class="nav-link" href="/web">Overview</a></li><li class="nav-item"><a class="nav-link" href="/web/get-started">Get started</a></li><li class="nav-item"><a class="nav-link" href="/web/deployment">Deployment</a></li><li class="nav-item"><a class="nav-link" href="/web/libraries">Libraries & packages</a></li><li class="nav-item"><a class="nav-link" href="/web/wasm">Wasm compilation</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/guides/environment-declarations">Environment declarations</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-6" role="button" aria-expanded="false" aria-controls="sidenav-6">Interoperability</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-6"><li class="nav-item"><a class="nav-link" href="/interop/c-interop">C interop</a></li><li class="nav-item"><a class="nav-link" href="/interop/objective-c-interop">Objective-C & Swift interop</a></li><li class="nav-item"><a class="nav-link" href="/interop/java-interop">Java & Kotlin interop</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-6-4" href="#sidenav-6-4" role="button" aria-expanded="false" aria-controls="sidenav-6-4">JavaScript interop</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-6-4"><li class="nav-item"><a class="nav-link" href="/interop/js-interop">Overview</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/usage">Usage</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/js-types">JS types</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/tutorials">Tutorials</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/past-js-interop">Past JS interop</a></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/interop/js-interop/package-web">Web interop</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-7" role="button" aria-expanded="false" aria-controls="sidenav-7">Tools & techniques</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7"><li class="nav-item"><a class="nav-link" href="/tools">Overview</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-2" href="#sidenav-7-2" role="button" aria-expanded="false" aria-controls="sidenav-7-2">Editors & debuggers</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-2"><li class="nav-item"><a class="nav-link" href="/tools/jetbrains-plugin">IntelliJ & Android Studio</a></li><li class="nav-item"><a class="nav-link" href="/tools/vs-code">VS Code</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-devtools">Dart DevTools</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-2-4" href="#sidenav-7-2-4" role="button" aria-expanded="false" aria-controls="sidenav-7-2-4">DartPad</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-2-4"><li class="nav-item"><a class="nav-link" href="/tools/dartpad">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tools/dartpad/troubleshoot">Troubleshooting DartPad</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-3" href="#sidenav-7-3" role="button" aria-expanded="false" aria-controls="sidenav-7-3">Command-line tools</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-3"><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" data-target="#sidenav-7-3-1" href="#sidenav-7-3-1" role="button" aria-expanded="true" aria-controls="sidenav-7-3-1">Dart SDK</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-7-3-1"><li class="nav-item"><a class="nav-link" href="/tools/sdk">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-tool">dart</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-analyze">dart analyze</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-compile">dart compile</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-create">dart create</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-doc">dart doc</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-fix">dart fix</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-format">dart format</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-info">dart info</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/cmd">dart pub</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-run">dart run</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-test">dart test</a></li><li class="nav-item"><a class="nav-link" href="/tools/dartaotruntime">dartaotruntime</a></li><li class="nav-item"><a class="nav-link" href="/tools/experiment-flags">Experiment flags</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" data-target="#sidenav-7-3-2" href="#sidenav-7-3-2" role="button" aria-expanded="true" aria-controls="sidenav-7-3-2">Other command-line tools</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-7-3-2"><li class="nav-item"><a class="nav-link" href="/tools/build_runner">build_runner</a></li><li class="nav-item"><a class="nav-link" href="/tools/webdev">webdev</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-4" href="#sidenav-7-4" role="button" aria-expanded="false" aria-controls="sidenav-7-4">Static analysis</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-4"><li class="nav-item"><a class="nav-link" href="/tools/analysis">Customizing static analysis</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/sound-problems">Fixing common type problems</a></li><li class="nav-item"><a class="nav-link" href="/tools/non-promotion-reasons">Fixing type promotion failures</a></li><li class="nav-item"><a class="nav-link" href="/tools/linter-rules">Linter rules</a></li><li class="nav-item"><a class="nav-link" href="/tools/diagnostic-messages">Diagnostic messages</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-5" href="#sidenav-7-5" role="button" aria-expanded="false" aria-controls="sidenav-7-5">Testing & optimization</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-5"><li class="nav-item"><a class="nav-link" href="/guides/testing">Testing</a></li><li class="nav-item"><a class="nav-link" href="/web/debugging">Debugging web apps</a></li></ul></li></ul></li><li aria-hidden="true"><div class="sidebar-primary-divider"></div></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-9" role="button" aria-expanded="false" aria-controls="sidenav-9">Resources</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-9"><li class="nav-item"><a class="nav-link" href="/resources/dart-cheatsheet">Language cheatsheet</a></li><li class="nav-item"><a class="nav-link" href="/resources/breaking-changes">Breaking changes</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/evolution">Language evolution</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/spec">Language specification</a></li><li class="nav-item"><a class="nav-link" href="/resources/dart-3-migration">Dart 3 migration guide</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-9-6" href="#sidenav-9-6" role="button" aria-expanded="false" aria-controls="sidenav-9-6">Coming from ...</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-9-6"><li class="nav-item"><a class="nav-link" href="/resources/coming-from/js-to-dart">JavaScript to Dart</a></li><li class="nav-item"><a class="nav-link" href="/resources/coming-from/swift-to-dart">Swift to Dart</a></li></ul></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/resources/faq">FAQ</a></li><li class="nav-item"><a class="nav-link" href="/resources/glossary">Glossary</a></li><li class="nav-item"><a class="nav-link" href="/resources/books">Books</a></li><li class="nav-item"><a class="nav-link" href="/resources/videos">Videos</a></li><li class="nav-item"><a class="nav-link" href="/tutorials">Tutorials</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" href="#sidenav-10" role="button" aria-expanded="true" aria-controls="sidenav-10">Related sites</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-10"><li class="nav-item"><a class="nav-link" href="https://api.dart.dev" target="_blank" rel="noopener">API reference</a></li><li class="nav-item"><a class="nav-link" href="https://medium.com/dartlang" target="_blank" rel="noopener">Blog</a></li><li class="nav-item"><a class="nav-link" href="https://dartpad.dev" target="_blank" rel="noopener">DartPad (online editor)</a></li><li class="nav-item"><a class="nav-link" href="https://flutter.dev" target="_blank" rel="noopener">Flutter</a></li><li class="nav-item"><a class="nav-link" href="https://pub.dev" target="_blank" rel="noopener">Package site</a></li></ul></li></ul></div></div><main id="page-content"><div id="site-toc--side" class="site-toc"><header class="site-toc__title">Contents</header><ul class="section-nav"><li class="toc-entry nav-item"><a class="nav-link" href="#running-an-app-with-the-standalone-dart-vm">Running an app with the standalone Dart VM</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#overview-of-the-dcat-app-code">Overview of the dcat app code</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#getting-dependencies">Getting dependencies</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#running-dcat">Running dcat</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#parsing-command-line-arguments">Parsing command-line arguments</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#reading-and-writing-with-stdin-stdout-and-stderr">Reading and writing with stdin, stdout, and stderr</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#stdout">stdout</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#stderr">stderr</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#stdin">stdin</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#getting-info-about-a-file">Getting info about a file</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#reading-a-file">Reading a file</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#writing-to-a-file">Writing to a file</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#getting-environment-information">Getting environment information</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#setting-exit-codes">Setting exit codes</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#summary">Summary</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#what-next">What next?</a></li></ul></div><article><div class="content"><nav id="subnav"><ul><li class="previous"><a href="/tutorials/server/get-started">&lang;  Get started: Command-line and server apps</a></li><li class="next"><a href="/tutorials/server/fetch-data">Fetch data from the internet  &rang;</a></li></ul></nav><div id="site-content-title"><h1>Write command-line apps</h1></div><div id="site-toc--inline" class="site-toc toc-collapsible toc-collapsed"><header class="site-toc__title">Contents keyboard_arrow_down keyboard_arrow_up</header><ul class="section-nav"><li class="toc-entry"><a href="#running-an-app-with-the-standalone-dart-vm">Running an app with the standalone Dart VM</a></li><li class="toc-entry"><a href="#overview-of-the-dcat-app-code">Overview of the dcat app code</a><ul><li class="toc-entry"><a href="#getting-dependencies">Getting dependencies</a></li><li class="toc-entry"><a href="#running-dcat">Running dcat</a></li></ul></li><li class="toc-entry"><a href="#parsing-command-line-arguments">Parsing command-line arguments</a></li><li class="toc-entry"><a href="#reading-and-writing-with-stdin-stdout-and-stderr">Reading and writing with stdin, stdout, and stderr</a><ul><li class="toc-entry"><a href="#stdout">stdout</a></li><li class="toc-entry"><a href="#stderr">stderr</a></li><li class="toc-entry"><a href="#stdin">stdin</a></li></ul></li><li class="toc-entry"><a href="#getting-info-about-a-file">Getting info about a file</a></li><li class="toc-entry"><a href="#reading-a-file">Reading a file</a></li><li class="toc-entry"><a href="#writing-to-a-file">Writing to a file</a></li><li class="toc-entry"><a href="#getting-environment-information">Getting environment information</a></li><li class="toc-entry"><a href="#setting-exit-codes">Setting exit codes</a></li><li class="toc-entry"><a href="#summary">Summary</a></li><li class="toc-entry"><a href="#what-next">What next?</a></li></ul>more_horiz</div> <?code-excerpt replace="/ ?\/\/!tip.*//g"?> <aside class="alert alert-secondary"><div class="alert-header">What's the point?</div><div class="alert-content"><ul><li>Command-line applications need to do input and output.</li><li>The <code>dart:io</code> library provides I/O functionality.</li><li>The args package helps define and parse command-line arguments.</li><li>A <code>Future</code> object represents a value that will be available at some time in the future.</li><li>Streams provide a series of asynchronous data events.</li><li>Most input and output requires the use of streams.</li></ul></div></aside><aside class="alert alert-info"><div class="alert-header">info Note</div><div class="alert-content">This tutorial uses the <code>async</code> and <code>await</code> language features, which rely on the <a href="https://api.dart.dev/dart-async/Future-class.html"><code>Future</code></a> and <a href="https://api.dart.dev/dart-async/Stream-class.html"><code>Stream</code></a> classes for asynchronous support. To learn more about these features, see the <a href="/libraries/async/async-await">asynchronous programming tutorial</a> and the <a href="/libraries/async/using-streams">streams tutorial</a>.</div></aside>This tutorial teaches you how to build command-line apps and shows you a few small command-line applications. These programs use resources that most command-line applications need, including the standard output, error, and input streams, command-line arguments, files and directories, and more.<div class="header-wrapper"><h2 id="running-an-app-with-the-standalone-dart-vm">Running an app with the standalone Dart VM</h2><a class="heading-link" href="#running-an-app-with-the-standalone-dart-vm" aria-label="Link to 'Running an app with the standalone Dart VM' section">#</a></div>To run a command-line app in the Dart VM, use <code>dart run</code>. The <code>dart</code> commands are included with the <a href="/tools/sdk">Dart SDK</a>.<aside class="alert alert-warning"><div class="alert-header">error Important</div><div class="alert-content">The location of the SDK installation directory (we'll call it <code><sdk-install-dir></code>) depends on your platform and how you installed the SDK. You can find <code>dart</code> in <code><sdk-install-dir>/bin</code>. By putting this directory in your PATH you can refer to the <code>dart</code> command by name.</div></aside>Let's run a small program.<ol><li>Create a file called <code>hello_world.dart</code> that contains this code: <?code-excerpt "misc/test/samples_test.dart (hello-world)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>void main() { print('Hello, World!'); }</code></pre></div></div></li><li>In the directory that contains the file you just created, run the program:<div class="code-block-wrapper language-console"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code>$ dart run hello_world.dart Hello, World!</code></pre></div></div></li></ol>The Dart tool supports many commands and options. Use <code>dart --help</code> to see commonly used commands and options. Use <code>dart --verbose</code> to see all options.<div class="header-wrapper"><h2 id="overview-of-the-dcat-app-code">Overview of the dcat app code</h2><a class="heading-link" href="#overview-of-the-dcat-app-code" aria-label="Link to 'Overview of the dcat app code' section">#</a></div>This tutorial covers the details of a small sample app called <code>dcat</code>, which displays the contents of any files listed on the command line. This app uses various classes, functions, and properties available to command-line apps. Continue on in the tutorial to learn about each part of the app and the various APIs used. <?code-excerpt "cli/bin/dcat.dart (dcat-app)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>import 'dart:convert'; import 'dart:io'; import 'package:args/args.dart'; const lineNumber = 'line-number'; void main(List<String> arguments) { exitCode = 0; // Presume success final parser = ArgParser()..addFlag(lineNumber, negatable: false, abbr: 'n'); ArgResults argResults = parser.parse(arguments); final paths = argResults.rest; dcat(paths, showLineNumbers: argResults[lineNumber] as bool); } Future<void> dcat(List<String> paths, {bool showLineNumbers = false}) async { if (paths.isEmpty) { // No files provided as arguments. Read from stdin and print each line. await stdin.pipe(stdout); } else { for (final path in paths) { var lineNumber = 1; final lines = utf8.decoder .bind(File(path).openRead()) .transform(const LineSplitter()); try { await for (final line in lines) { if (showLineNumbers) { stdout.write('${lineNumber++} '); } stdout.writeln(line); } } catch (_) { await _handleError(path); } } } } Future<void> _handleError(String path) async { if (await FileSystemEntity.isDirectory(path)) { stderr.writeln('error: $path is a directory'); } else { exitCode = 2; } }</code></pre></div></div><div class="header-wrapper"><h3 id="getting-dependencies">Getting dependencies</h3><a class="heading-link" href="#getting-dependencies" aria-label="Link to 'Getting dependencies' section">#</a></div>You might notice that dcat depends on a package named args. To get the args package, use the <a href="/tools/pub/packages">pub package manager</a>.A real app has tests, license files, dependency files, examples, and so on. For the first app though, we can easily create only what is necessary with the <a href="/tools/dart-create"><code>dart create</code></a> command.<ol><li>Inside a directory, create the dcat app with the dart tool.<div class="code-block-wrapper language-console"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code>$ dart create dcat</code></pre></div></div></li><li>Change to the created directory.<div class="code-block-wrapper language-console"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code>$ cd dcat</code></pre></div></div></li><li>Inside the <code>dcat</code> directory, use <a href="/tools/pub/cmd/pub-add"><code>dart pub add</code></a> to add the <code>args</code> package as a dependency. This adds <code>args</code> to the list of your dependencies found in the <code>pubspec.yaml</code> file.<div class="code-block-wrapper language-console"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code>$ dart pub add args</code></pre></div></div></li><li>Open the <code>bin/dcat.dart</code> file and copy the preceding code into it.</li></ol><aside class="alert alert-info"><div class="alert-header">info Note</div><div class="alert-content">To learn more about using packages and organizing your code, check out <a href="/tools/pub/packages">How to use packages</a> and <a href="/tools/pub/package-layout">Package layout conventions</a>.</div></aside><div class="header-wrapper"><h3 id="running-dcat">Running dcat</h3><a class="heading-link" href="#running-dcat" aria-label="Link to 'Running dcat' section">#</a></div>Once you have your app's dependencies, you can run the app from the command line over any text file, like <code>pubspec.yaml</code>:<div class="code-block-wrapper language-console"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code>$ dart run bin/dcat.dart -n pubspec.yaml 1 name: dcat 2 description: A sample command-line application. 3 version: 1.0.0 4 # repository: https://github.com/my_org/my_repo 5 6 environment: 7 sdk: ^3.5.4 8 9 # Add regular dependencies here. 10 dependencies: 11 args: ^2.5.0 12 # path: ^1.8.0 13 14 dev_dependencies: 15 lints: ^4.0.0 16 test: ^1.24.0</code></pre></div></div>This command displays each line of the specified file. Because you specified the <code>-n</code> option, a line number is displayed before each line.<div class="header-wrapper"><h2 id="parsing-command-line-arguments">Parsing command-line arguments</h2><a class="heading-link" href="#parsing-command-line-arguments" aria-label="Link to 'Parsing command-line arguments' section">#</a></div>The <a href="https://pub.dev/packages/args">args package</a> provides parser support for transforming command-line arguments into a set of options, flags, and additional values. Import the package's <a href="https://pub.dev/documentation/args/latest/args/args-library.html">args library</a> as follows: <?code-excerpt "cli/bin/dcat.dart" retain="package:args"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>import 'package:args/args.dart';</code></pre></div></div>The <code>args</code> library contains these classes, among others:<div class="table-wrapper"><table class="table"><thead><tr><th>Class</th><th>Description</th></tr></thead><tbody><tr><td><a href="https://pub.dev/documentation/args/latest/args/ArgParser-class.html">ArgParser</a></td><td>A command-line argument parser.</td></tr><tr><td><a href="https://pub.dev/documentation/args/latest/args/ArgResults-class.html">ArgResults</a></td><td>The result of parsing command-line arguments using <code>ArgParser</code>.</td></tr></tbody></table></div>The following code in the <code>dcat</code> app uses these classes to parse and store the specified command-line arguments: <?code-excerpt "cli/bin/dcat.dart (arg-processing)" plaster="none" replace="/(ArgR.*|List[^\)]*|\..*|parser.*|argResults\S[^);]+)/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>void main(List<String> arguments) { exitCode = 0; // Presume success final parser = ArgParser()..addFlag(lineNumber, negatable: false, abbr: 'n'); ArgResults argResults = parser.parse(arguments); final paths = argResults.rest; dcat(paths, showLineNumbers: argResults[lineNumber] as bool); }</code></pre></div></div>The Dart runtime passes command-line arguments to the app's <code>main</code> function as a list of strings. The <code>ArgParser</code> is configured to parse the <code>-n</code> option. Then, the result of parsing command-line arguments is stored in <code>argResults</code>.The following diagram shows how the <code>dcat</code> command line used above is parsed into an <code>ArgResults</code> object.<img src="/assets/img/tutorials/server/dcat-dart-run.svg" alt="Run dcat from the command-line">You can access flags and options by name, treating an <code>ArgResults</code> like a <code>Map</code>. You can access other values using the <code>rest</code> property.The <a href="https://pub.dev/documentation/args/latest/args/args-library.html">API reference</a> for the <code>args</code> library provides detailed information to help you use the <code>ArgParser</code> and <code>ArgResults</code> classes.<div class="header-wrapper"><h2 id="reading-and-writing-with-stdin-stdout-and-stderr">Reading and writing with stdin, stdout, and stderr</h2><a class="heading-link" href="#reading-and-writing-with-stdin-stdout-and-stderr" aria-label="Link to 'Reading and writing with stdin, stdout, and stderr' section">#</a></div>Like other languages, Dart has standard output, standard error, and standard input streams. The standard I/O streams are defined at the top level of the <code>dart:io</code> library:<div class="table-wrapper"><table class="table"><thead><tr><th>Stream</th><th>Description</th></tr></thead><tbody><tr><td><a href="https://api.dart.dev/dart-io/stdout.html">stdout</a></td><td>The standard output</td></tr><tr><td><a href="https://api.dart.dev/dart-io/stderr.html">stderr</a></td><td>The standard error</td></tr><tr><td><a href="https://api.dart.dev/dart-io/stdin.html">stdin</a></td><td>The standard input</td></tr></tbody></table></div>Import the <code>dart:io</code> library as follows: <?code-excerpt "cli/bin/dcat.dart" retain="dart:io"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>import 'dart:io';</code></pre></div></div><aside class="alert alert-info"><div class="alert-header">info Note</div><div class="alert-content">Web apps (apps that depend on <code>dart:html</code>) can't use the <code>dart:io</code> library.</div></aside><div class="header-wrapper"><h3 id="stdout">stdout</h3><a class="heading-link" href="#stdout" aria-label="Link to 'stdout' section">#</a></div>The following code from the <code>dcat</code> app writes the line numbers to <code>stdout</code> (if the <code>-n</code> option is specified) followed by the contents of the line from the file. <?code-excerpt "cli/bin/dcat.dart (show-line-numbers)" replace="/stdout\..*/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>if (showLineNumbers) { stdout.write('${lineNumber++} '); } stdout.writeln(line);</code></pre></div></div>The <code>write()</code> and <code>writeln()</code> methods take an object of any type, convert it to a string, and print it. The <code>writeln()</code> method also prints a newline character. The <code>dcat</code> app uses the <code>write()</code> method to print the line number so the line number and text appear on the same line.You can also use the <code>writeAll()</code> method to print a list of objects, or use <code>addStream()</code> to asynchronously print all the elements from a stream.<code>stdout</code> provides more functionality than the <code>print()</code> function. For example, you can display the contents of a stream with <code>stdout</code>. However, you must use <code>print()</code> instead of <code>stdout</code> for apps that run on the web.<div class="header-wrapper"><h3 id="stderr">stderr</h3><a class="heading-link" href="#stderr" aria-label="Link to 'stderr' section">#</a></div>Use <code>stderr</code> to write error messages to the console. The standard error stream has the same methods as <code>stdout</code>, and you use it in the same way. Although both <code>stdout</code> and <code>stderr</code> print to the console, their output is separate and can be redirected or piped in the command line or programmatically to different destinations.The following code from the <code>dcat</code> app prints an error message if the user tries to output the lines of a directory instead of a file. <?code-excerpt "cli/bin/dcat.dart (await-entity)" replace="/stderr\..*/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>if (await FileSystemEntity.isDirectory(path)) { stderr.writeln('error: $path is a directory'); } else { exitCode = 2; }</code></pre></div></div><div class="header-wrapper"><h3 id="stdin">stdin</h3><a class="heading-link" href="#stdin" aria-label="Link to 'stdin' section">#</a></div>The standard input stream typically reads data synchronously from the keyboard, although it can read asynchronously and get input piped in from the standard output of another program.Here's a small program that reads a single line from <code>stdin</code>: <?code-excerpt "cli/bin/dcat_stdin.dart"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>import 'dart:io'; void main() { stdout.writeln('Type something'); final input = stdin.readLineSync(); stdout.writeln('You typed: $input'); }</code></pre></div></div>The <code>readLineSync()</code> method reads text from the standard input stream, blocking until the user types in text and presses return. This little program prints out the typed text.In the <code>dcat</code> app, if the user does not provide a filename on the command line, the program instead reads from stdin using the <code>pipe()</code> method. Because <code>pipe()</code> is asynchronous (returning a <code>Future</code>, even though this code doesn't use that return value), the code that calls it uses <code>await</code>. <?code-excerpt "cli/bin/dcat.dart (pipe)" replace="/pipe/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>await stdin.pipe(stdout);</code></pre></div></div>In this case, the user types in lines of text, and the app copies them to stdout. The user signals the end of input by pressing <kbd>Control</kbd>+<kbd>D</kbd> (or <kbd>Control</kbd>+<kbd>Z</kbd> on Windows).<div class="code-block-wrapper language-console"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code>$ dart run bin/dcat.dart The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog.</code></pre></div></div><div class="header-wrapper"><h2 id="getting-info-about-a-file">Getting info about a file</h2><a class="heading-link" href="#getting-info-about-a-file" aria-label="Link to 'Getting info about a file' section">#</a></div>The <a href="https://api.dart.dev/dart-io/FileSystemEntity-class.html"><code>FileSystemEntity</code></a> class in the <code>dart:io</code> library provides properties and static methods that help you inspect and manipulate the file system.For example, if you have a path, you can determine whether the path is a file, a directory, a link, or not found by using the <code>type()</code> method from the <code>FileSystemEntity</code> class. Because the <code>type()</code> method accesses the file system, it performs the check asynchronously.The following code from the <code>dcat</code> app uses <code>FileSystemEntity</code> to determine if the path provided on the command line is a directory. The returned <code>Future</code> completes with a boolean that indicates if the path is a directory or not. Because the check is asynchronous, the code calls <code>isDirectory()</code> using <code>await</code>. <?code-excerpt "cli/bin/dcat.dart (await-entity)" replace="/await.*path\)/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>if (await FileSystemEntity.isDirectory(path)) { stderr.writeln('error: $path is a directory'); } else { exitCode = 2; }</code></pre></div></div>Other interesting methods in the <code>FileSystemEntity</code> class include <code>isFile()</code>, <code>exists()</code>, <code>stat()</code>, <code>delete()</code>, and <code>rename()</code>, all of which also use a <code>Future</code> to return a value.<code>FileSystemEntity</code> is the superclass for the <code>File</code>, <code>Directory</code>, and <code>Link</code> classes.<div class="header-wrapper"><h2 id="reading-a-file">Reading a file</h2><a class="heading-link" href="#reading-a-file" aria-label="Link to 'Reading a file' section">#</a></div>The <code>dcat</code> apps opens each file listed on the command line with the <code>openRead()</code> method, which returns a <code>Stream</code>. The <code>await for</code> block waits for the file to be read and decoded asynchronously. When the data becomes available on the stream, the app prints it to stdout. <?code-excerpt "cli/bin/dcat.dart (for-path)" remove="/^\s*\/\/!tip.*/" replace="/( )((await for| *stdout| *if| *}).*)/$1[!$2!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>for (final path in paths) { var lineNumber = 1; final lines = utf8.decoder .bind(File(path).openRead()) .transform(const LineSplitter()); try { await for (final line in lines) { if (showLineNumbers) { stdout.write('${lineNumber++} '); } stdout.writeln(line); } } catch (_) { await _handleError(path); } }</code></pre></div></div>The following highlights the rest of the code, which uses two decoders that transform the data before making it available in the <code>await for</code> block. The UTF8 decoder converts the data into Dart strings. <code>LineSplitter</code> splits the data at newlines. <?code-excerpt "cli/bin/dcat.dart (for-path)" remove="/^\s*\/\/!tip.*/" replace="/utf8.decoder|LineSplitter()/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>for (final path in paths) { var lineNumber = 1; final lines = utf8.decoder .bind(File(path).openRead()) .transform(const LineSplitter()); try { await for (final line in lines) { if (showLineNumbers) { stdout.write('${lineNumber++} '); } stdout.writeln(line); } } catch (_) { await _handleError(path); } }</code></pre></div></div>The <code>dart:convert</code> library provides these and other data converters, including one for JSON. To use these converters you need to import the <code>dart:convert</code> library: <?code-excerpt "cli/bin/dcat.dart" retain="dart:convert"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>import 'dart:convert';</code></pre></div></div><div class="header-wrapper"><h2 id="writing-to-a-file">Writing to a file</h2><a class="heading-link" href="#writing-to-a-file" aria-label="Link to 'Writing to a file' section">#</a></div>The easiest way to write text to a file is to create a <a href="https://api.dart.dev/dart-io/File-class.html"><code>File</code></a> object and use the <code>writeAsString()</code> method: <?code-excerpt "cli/lib/cmdline.dart (write-quote)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>final quotes = File('quotes.txt'); const stronger = 'That which does not kill us makes us stronger. -Nietzsche'; await quotes.writeAsString(stronger, mode: FileMode.append);</code></pre></div></div>The <code>writeAsString()</code> method writes the data asynchronously. It opens the file before writing and closes the file when done. To append data to an existing file, you can use the optional named parameter <code>mode</code> and set its value to <code>FileMode.append</code>. Otherwise, the mode defaults to <code>FileMode.write</code> and the previous contents of the file, if any, are overwritten.If you want to write more data, you can open the file for writing. The <code>openWrite()</code> method returns an <code>IOSink</code>, which has the same type as stdin and stderr. When using the <code>IOSink</code> returned from <code>openWrite()</code>, you can continue to write to the file until done, at which time, you must manually close the file. The <code>close()</code> method is asynchronous and returns a <code>Future</code>. <?code-excerpt "cli/lib/cmdline.dart (write-quotes)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>final quotes = File('quotes.txt').openWrite(mode: FileMode.append); quotes.write("Don't cry because it's over, "); quotes.writeln('smile because it happened. -Dr. Seuss'); await quotes.close();</code></pre></div></div><div class="header-wrapper"><h2 id="getting-environment-information">Getting environment information</h2><a class="heading-link" href="#getting-environment-information" aria-label="Link to 'Getting environment information' section">#</a></div>Use the <a href="https://api.dart.dev/dart-io/Platform-class.html"><code>Platform</code></a> class to get information about the machine and operating system that your app is running on.The static <a href="https://api.dart.dev/dart-io/Platform/environment.html"><code>Platform.environment</code></a> property provides a copy of the environment variables in an immutable map. If you need a mutable map (modifiable copy) you can use <code>Map.of(Platform.environment)</code>. <?code-excerpt "cli/lib/cmdline.dart (env)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>final envVarMap = Platform.environment; print('PWD = ${envVarMap['PWD']}'); print('LOGNAME = ${envVarMap['LOGNAME']}'); print('PATH = ${envVarMap['PATH']}');</code></pre></div></div><code>Platform</code> provides other useful properties that give information about the machine, OS, and currently running app. For example:<ul><li><a href="https://api.dart.dev/dart-io/Platform/isMacOS.html"><code>Platform.isMacOS()</code></a></li><li><a href="https://api.dart.dev/dart-io/Platform/numberOfProcessors.html"><code>Platform.numberOfProcessors</code></a></li><li><a href="https://api.dart.dev/dart-io/Platform/script.html"><code>Platform.script</code></a></li></ul><div class="header-wrapper"><h2 id="setting-exit-codes">Setting exit codes</h2><a class="heading-link" href="#setting-exit-codes" aria-label="Link to 'Setting exit codes' section">#</a></div>The <code>dart:io</code> library defines a top-level property, <code>exitCode</code>, that you can change to set the exit code for the current invocation of the Dart VM. An exit code is a number passed from a Dart app to the parent process to indicate the success, failure, or other state of the execution of the app.The <code>dcat</code> app sets the exit code in the <code>_handleError()</code> function to indicate that an error occurred during execution. <?code-excerpt "cli/bin/dcat.dart (handle-error)" remove="/^\s*\/\/!tip.*/" replace="/exit.*;/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>Future<void> _handleError(String path) async { if (await FileSystemEntity.isDirectory(path)) { stderr.writeln('error: $path is a directory'); } else { exitCode = 2; } }</code></pre></div></div>An exit code of <code>2</code> indicates that the app encountered an error.An alternative to using <code>exitCode</code> is to use the top-level <code>exit()</code> function, which sets the exit code and exits the app immediately. For example, the <code>_handleError()</code> function could call <code>exit(2)</code> instead of setting <code>exitCode</code> to 2, but <code>exit()</code> would quit the program and it might not process all of the files specified by the running command.<aside class="alert alert-info"><div class="alert-header">info Note</div><div class="alert-content">Generally speaking, you're better off using the <code>exitCode</code> property, which sets the exit code but allows the program to continue through to its natural completion.</div></aside>Although you can use any number for an exit code, by convention, the codes in the table below have the following meanings:<div class="table-wrapper"><table class="table"><thead><tr><th>Code</th><th>Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Warnings</td></tr><tr><td>2</td><td>Errors</td></tr></tbody></table></div><div class="header-wrapper"><h2 id="summary">Summary</h2><a class="heading-link" href="#summary" aria-label="Link to 'Summary' section">#</a></div>This tutorial described some basic APIs found in the following classes from the <code>dart:io</code> library:<div class="table-wrapper"><table class="table"><thead><tr><th>API</th><th>Description</th></tr></thead><tbody><tr><td><a href="https://api.dart.dev/dart-io/IOSink-class.html"><code>IOSink</code></a></td><td>Helper class for objects that consume data from streams</td></tr><tr><td><a href="https://api.dart.dev/dart-io/File-class.html"><code>File</code></a></td><td>Represents a file on the native file system</td></tr><tr><td><a href="https://api.dart.dev/dart-io/Directory-class.html"><code>Directory</code></a></td><td>Represents a directory on the native file system</td></tr><tr><td><a href="https://api.dart.dev/dart-io/FileSystemEntity-class.html"><code>FileSystemEntity</code></a></td><td>Superclass for File and Directory</td></tr><tr><td><a href="https://api.dart.dev/dart-io/Platform-class.html"><code>Platform</code></a></td><td>Provides information about the machine and operating system</td></tr><tr><td><a href="https://api.dart.dev/dart-io/stdout.html"><code>stdout</code></a></td><td>The standard output stream</td></tr><tr><td><a href="https://api.dart.dev/dart-io/stderr.html"><code>stderr</code></a></td><td>The standard error stream</td></tr><tr><td><a href="https://api.dart.dev/dart-io/stdin.html"><code>stdin</code></a></td><td>The standard input stream</td></tr><tr><td><a href="https://api.dart.dev/dart-io/exitCode.html"><code>exitCode</code></a></td><td>Access and set the exit code</td></tr><tr><td><a href="https://api.dart.dev/dart-io/exit.html"><code>exit()</code></a></td><td>Sets the exit code and quits</td></tr></tbody></table></div>In addition, this tutorial covered two classes from <code>package:args</code> that help with parsing and using command-line arguments: <a href="https://pub.dev/documentation/args/latest/args/ArgParser-class.html"><code>ArgParser</code></a> and <a href="https://pub.dev/documentation/args/latest/args/ArgResults-class.html"><code>ArgResults</code></a>.For more classes, functions, and properties, consult the API docs for <a href="https://api.dart.dev/dart-io/dart-io-library.html"><code>dart:io</code></a>, <a href="https://api.dart.dev/dart-convert/dart-convert-library.html"><code>dart:convert</code></a>, and <a href="https://pub.dev/documentation/args/latest/args/args-library.html"><code>package:args</code></a>.For another example of a command line app, check out the <a href="https://github.com/dart-lang/samples/tree/main/command_line"><code>command_line</code></a> sample.<div class="header-wrapper"><h2 id="what-next">What next?</h2><a class="heading-link" href="#what-next" aria-label="Link to 'What next?' section">#</a></div>If you're interested in server-side programming, check out the <a href="/tutorials/server/httpserver">next tutorial</a>.<nav id="subnav"><ul><li class="previous"><a href="/tutorials/server/get-started">&lang;  Get started: Command-line and server apps</a></li><li class="next"><a href="/tutorials/server/fetch-data">Fetch data from the internet  &rang;</a></li></ul></nav>Unless stated otherwise, the documentation on this site reflects Dart 3.5.4. Page last updated on 2024-11-18. <a href="https://github.com/dart-lang/site-www/tree/main/src/content/tutorials/server/cmdline.md" target="_blank" rel="noopener">View source</a> or <a href="https://github.com/dart-lang/site-www/issues/new?template=1_page_issue.yml&page-url=https://dart.dev/tutorials/server/cmdline/&page-source=https://github.com/dart-lang/site-www/tree/main/src/content/tutorials/server/cmdline.md" title="Report an issue with this page" target="_blank" rel="noopener">report an issue</a>.</div></article></main><footer id="page-footer"><div class="footer-section footer-main"><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart" width="164"></a><div class="footer-social-links"><a href="https://medium.com/dartlang" target="_blank" rel="noopener" title="Medium blog"><svg><use href="/assets/img/social/medium.svg#medium"></use></svg> </a><a href="https://github.com/dart-lang" target="_blank" rel="noopener" title="GitHub"><svg><use href="/assets/img/social/github.svg#github"></use></svg> </a><a href="https://twitter.com/dart_lang" target="_blank" rel="noopener" title="X (Twitter)"><svg><use href="/assets/img/social/x.svg#x"></use></svg></a></div></div><div class="footer-section footer-tray"><div class="footer-licenses">Except as otherwise noted, this site is licensed under a <a href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>, and code samples are licensed under the <a href="https://opensource.org/licenses/BSD-3-Clause">3-Clause BSD License</a>.</div><div class="footer-utility-links"><ul><li><a href="/terms" title="Terms of use">Terms</a></li><li><a href="https://policies.google.com/privacy" target="_blank" rel="noopener" title="Privacy policy">Privacy</a></li><li><a href="/security" title="Security philosophy and practices">Security</a></li></ul></div></div></footer></body></html>