Meet the Notion CLI: Built for Agents & Humans

Hey, I'm Carter. I'm on the team that helps deliver the Notion CLI. And today, I want to talk about four of the key design principles we use when building the CLI. And I'm Anthony, also a software engineer here on Carter's team. But I didn't get anywhere near as deep into the weeds as Carter did. So, I'm going to make sure he really breaks this down for us here.

Okay, we'll get started. Install the CLI here. — Cool. and you immediately can see some of the commands available. I want to talk about the first principle progressive disclosure. So if you run ntn help, you see all the top level commands available. And this isn't everything the notion CLI can do. This is just the top level name spaces. We don't want to dump all you know every single possible command on users or agents uh from the get-go. We want to allow exploration. — Yeah. — Right. So here you can see well there's data sources, files, pages and each of these perhaps has subcomands that you can drill in and continue to explore and learn. — Yeah. So I think workers is a good one because it's very deep actually. So NTN workers you can run this and you see that there are like additional subcomands you might need to run. So NTN workers help. — Oh yeah. Okay. There's a lot you can do underneath the workers namespace. — under the workers namespace. That's exactly right. And importantly with this noun verb structure of ntn workers command, you know that all this is all you can do with workers. — So this is exhaustive for workers. — I see. — Um it's funny that like you don't want to dump too much on humans because it'll overwhelm them. And it's kind of the same for agents too and the context windows. — That's exactly right. If we print too much information that actually costs users money in our context window, causes compaction. It's bad for your session. So um — and so are this is this the exhaustive list of everything with workers? — So this is the exhaustive list of subcomands in the workers namespace — and some of these of course can also have different options available. — I see you just keep progressing down — right this tree shape. So — what's a good example of that? So yes, we like NTN worker sync, right? Which says manage syncable capabilities, — right? — So we can see what those options are. Okay, you can trigger, you can manage syncable state, get the status, and you have some of other options like verbose here. So right — this concept of like be able to drill in and like explore and learn what's in the CLI with these help commands is an important part of progressive disclosure.

disclosure. So the next thing I want to walk through here are the error messages and how we try to make those actionable. So for example, ntn worker sync trigger. We just saw that command in our help docs. But if you run it, it actually fails and we could throw an opaque error, but instead we give you this usage, right? NTN worker sync trigger requires a key, — right? It's almost like I can just copy and paste that and use it. It's very straightforward what the next step is. — That's right. So hopefully this is like already a very actionable error. But sometimes also error messages can be sort of more sophisticated. So this command will query a data source by ID and in this case it's actually 404 not found. — Well, that is what the server responds like this CLI can't find that data source. But what's likely happening here and we want to provide this feedback for users is that this data source simply isn't shared with the CLI key. — I see. So like programmatically it's a 404. But what we know is probably happening is you just don't have permission to access the data. That's right. So give that next step to the user. — Yeah, exactly. And sometimes it's also helpful to like drill in to the exact API request made from the CLI in case you're like as a developer you really are curious to see. — Yeah. So here you can see like the full response, the request that was made and our interpretation of that. It's and it kind of builds on the progressive disclosure where you don't want to see this every time but we let you just keep digging in drilling and this can help you help yourself um help an agent help you out or you know you can provide this to us for feedback on what's going wrong. — That's exactly right.

— So the next thing I want to talk about standard out and standard error and how we use these to facilitate scripting on top of the CLI. So for example, NPN workers list JSON verbose will give you some data back about what workers you have and that's the white text here at the bottom and it'll also give you auxiliary information verbosely about that request which is like the grayed out text above and the data your workers list here is going to standard out and the auxiliary request has gone to standard error. Oh, so this is both standard error and then standard out but all just printing out to the terminal. — That's right. — Okay. Okay, I would not think to put auxiliary data to standard error. So why would I do that? — That's right. Looking at it here, it hardly matters. But this becomes really important when you want to script on top of um the CLI, right? So if we're adding all auxiliary messages to standard out, you can't then pipe that to jq and extract for instance your ids, right? Information would corrupt the JSON payload. So by separating these to two different file descriptors you can you know both give that helpful information that people have requested the verbose while still allowing you know piping to jq or a — that's great I think it's pretty easy to just sit there and just pipe everything to standard out without really thinking about this but it's a great distinction — that's right you can't just print line everything from the CLI

— yeah lastly I want to talk about interactive and non-interactive modes in the terminal and how the CLI is built for both and you know So far everything we built in the CLI is really good for both developers and also agents right humans and agents. This last one is sort of the fork and respecting both an interactive terminal for uh human developers as well as a non-interactive terminal for agents is critical to building a good modern CLI. So a really good example of that is login. Um we want to be a great experience for users in the terminal. So, we give you this prompt. Well, where do you want to log into um or authenticate with a new workspace? But an agent or script can't choose a prompt interactively. Right. — So, I can show what this looks like from the perspective of agent like simulates nonty here. — That's right. Exactly. So, this will allow our CLI to like detect that it's a non-interactive uh execution just like a script or an agent. And here the login command actually falls back to a completely different behavior built for scripts and agents. So it — actually we provide this hint for agents like show this URL to your user ask them to click it and then run this other command pull to wait for the user to authenticate. — It's interesting. You basically customize the CLI based on if it's an agent or a human just by detecting if TTY is enabled or not. — That's right. You can automatically detect it and then configure your command for the audience.

Okay, we covered a lot today. Anthony, you want to bring us through those four? Remember the four high points? Yeah. Um, progressive disclosure, actionable errors, standard out versus standard error, and interactive versus non-interactive. So, it's a lot to be thinking about all this when we were building the CLI. Really, the first thing we did is actually dump all this into a markdown file, and that helped us adhere to this as we're building. And yeah, we hope it landed us on a CLI that's really good for humans, really good for agents, uh can oneshot building a worker, and we hope you find that's the case if you choose to download the CLI and give it a try.