Command reference ยท Cursor CLI
agent create-chat
Creates a new, empty chat and returns its ID, e.g. for use in scripts.
agent create-chat creates a new, empty chat session and only prints its chat ID to the console, without opening an interactive session or sending a prompt. The command is thus suited for scripts and automation that want to first reserve a session ID and then address it specifically. The returned ID can be picked up again with the global option --resume [chatId], for example to send prompts into exactly that session from a separate process or script. This distinguishes the command from agent ls, which lists existing chats from all workspaces, and from agent resume, which without an ID specified directly continues the most recently active session. create-chat belongs to the same command family as login, logout, status, and models, all documented via agent help [command].
โ WHEN TO USE IT?
Reserving a session ID in advance to address it later from a script via --resume
CHAT_ID=$(agent create-chat); agent --resume "$CHAT_ID" -p "start task"
Pre-creating multiple independent chat IDs before distributing prompts
for i in 1 2 3; do agent create-chat; done > chat-ids.txt
โ WHEN NOT TO?
Wanting to jump right in and chat with the agent immediately
agent create-chat only creates an empty session, but doesn't send a prompt or start a conversation.
Better: just use agent or agent "<prompt>"
Finding and resuming an earlier session
create-chat always creates a new, empty chat ID instead of searching for an existing one.
Better: use agent ls to list, or agent resume for the most recently active session
SOURCES
- Cursor Docs โ CLI Reference: Parameters โ cursor.com
MORE COMMANDS ยท Cursor CLI