{"slug": "agentics-design-principles-for-building-an-agent-first-cli", "title": "Agentics: Design Principles for Building an Agent-First CLI", "summary": "Agentics introduces design principles for building command-line interfaces (CLIs) optimized for AI agents as primary users, emphasizing no colored output, no interactivity, recursive help messages, and error recovery via nearest-neighbor suggestions. The approach aims to reduce token consumption and improve agent efficiency by leveraging CLIs over MCP servers for critical integrations.", "body_md": "# Agentics: Design Principles for Building an Agent-First CLI\n\n### What does 'agent first' mean in practice?\n\nAgents are increasingly picking up more and more of our workload. We use agents to [write and ship code](https://12gramsofcarbon.com/p/averaging-10-prs-a-day-with-claude), publish our [dev blog](https://noriagentic.com/newsletter.html#devlog), and even [write our board decks](https://12gramsofcarbon.com/p/agentics-powerpoint-is-dead). To make that all work, we have to give our agents access to more data sources. Slack, email, GitHub, aws, linear, datadog, sentry. For most of these tools, we can just pull an MCP server and call it a day. But MCP is extremely token hungry, and often implemented really poorly. For some critical integrations, we want to own the integration point.\n\nWhen building out a new integration, we often reach for CLIs over trying to build a custom MCP. CLIs have built-in progressive disclosure (they do not suck up tokens with parameter descriptions for function calls unless your model absolutely needs to know). The models are extremely familiar with using and calling CLIs through bash. And the models are very good at *writing* efficient CLI tools, because they have tons and tons of examples.\n\nCLIs that are built for agents as their primary user behave differently than those built for humans. We’ve spent a lot of time thinking about what that behavior difference ought to look like. In no particular order, here are a few principles we use when building CLI tools that assume agents are the primary consumer.\n\nNo colored output. No spinners. No animations. These waste tokens and are probably unappreciated by an agent that can’t see the visual media.\n\nNo interactivity at any point. Everything must be accessible through flags and stdout/stderr output.\n\nCalling the cli with empty,\n\n`--help`\n\n,`--list`\n\n, etc. should list a full description of what the tool can do at a high level and descriptions of individual commands (”use this command for…”). Overlap is fine here, we want to make it easy for the agent to stumble onto instructions.Help messages should be recursive. Calling\n\n`foo --help`\n\nshould explain what the CLI does broadly. Calling`foo bar --help`\n\nshould explain what the bar command does within foo, including any parameters that bar may need. Aim for 100% docs coverage.Every error or help message should include a file path for where the relevant code path is stored on disk, and a message encouraging the model to look up the source if needed.\n\nRelated: we generally install the CLI by building from source or bundling source where possible, so that the decompressed source is present for the model to figure out what to do.\n\nMake it easy for the agent to fix itself. If the agent tries a command that doesn’t work, do a nearest neighbor lookup. “Did you mean…” but for CLI commands.\n\nYou can find all of this in skill form [here](https://noriskillsets.dev/skills/building-agentic-cli-tools). Just drop it into your agent of choice, or run\n\n```\nnpx nori-skillsets install amol\n```\n\nto download my personal agent config (which includes the agentic cli skill already in place).\n\nWe’ve built a few different CLI tools that follow these principles, including:\n\n[nori-slack-cli](https://www.npmjs.com/package/nori-slack-cli), a thin command-line wrapper around the Slack Web API that maps 1:1 to Bolt (@slack/web-api). Every method Bolt exposes is reachable through a single dynamic command — there is no curated subset, no opinionated abstraction layer, and no business logic. If Bolt can call it, this CLI can call it.[nori-newsletter-cli](https://github.com/tilework-tech/nori-newsletter-cli), a CLI for managing and sending newsletters via AWS SES. Handles subscriber management through SES contact lists, CSV import, and individual email sending with automatic unsubscribe support.[1](#footnote-1)[nori-luma-cli](https://github.com/tilework-tech/nori-luma-cli), a wrapper around the Luma event manager API, so the agents can plan your parties for you! 🥳🥳🥳[nori-discord-cli](https://github.com/tilework-tech/nori-discord-cli), which is like the slack cli but for discord.[nori-shopify-cli](https://github.com/tilework-tech/nori-shopify-cli), which lets your agent access the*admin*tools in shopify.\n\nAll of these are open source, so feel free to drop them with your agents and see how they use the tools.\n\n*Agentics is the study of how to use and reason about agents. If you are an expert in coding agents, or interested in learning more about agents, join our community slack. More articles here.*\n\n*If you are trying to build background agents, we can help! We build white-labeled custom background agents that work like Ramp Inspect for our customers. Check out norisessions.com for more.*", "url": "https://wpnews.pro/news/agentics-design-principles-for-building-an-agent-first-cli", "canonical_source": "https://12gramsofcarbon.com/p/agentics-design-principles-for-building", "published_at": "2026-07-09 13:04:11+00:00", "updated_at": "2026-07-09 13:15:00.783224+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "artificial-intelligence"], "entities": ["Agentics", "MCP", "Slack", "AWS SES", "Luma", "nori-slack-cli", "nori-newsletter-cli", "nori-luma-cli"], "alternates": {"html": "https://wpnews.pro/news/agentics-design-principles-for-building-an-agent-first-cli", "markdown": "https://wpnews.pro/news/agentics-design-principles-for-building-an-agent-first-cli.md", "text": "https://wpnews.pro/news/agentics-design-principles-for-building-an-agent-first-cli.txt", "jsonld": "https://wpnews.pro/news/agentics-design-principles-for-building-an-agent-first-cli.jsonld"}}