Skip to content
Help articles

Add files from your computer with your AI

Set up the Listspace command line once, then ask your AI to attach a file.

An agent that works on your computer, such as Claude Code, Codex or Cursor, can put files from your disk on an item: a contract PDF, a screenshot of a bug, the spreadsheet from a meeting. It does this with the Listspace command line, which reads the file and uploads it. Set it up once.

Set it up

  1. In Listspace, open Settings, then Your AI, and create a token under API tokens. Choose Read and write. The token is shown only once, so copy it.
  2. In a terminal on your computer, run npx listspace login and paste the token when it asks. It needs Node.js 20 or later.
  3. Set the board's agent access level to 4 (Act) or higher. A file cannot wait in the Inbox, so below Act it is refused. See the Inbox and agent access.

The token is saved on your computer, outside your project folder. Never paste it into a chat.

Ask your AI

Tell it which file and which item, for example: Attach ~/Documents/contract.pdf to the Onboarding item on my Website board. The agent finds the item and runs the command for you.

You can also run it yourself, with the item's id and one or more files:

npx listspace attach <item id> contract.pdf screenshot.png

What you can attach

  • Images, PDFs, Word, Excel and PowerPoint files, text, markdown, CSV and JSON, zip, rar and 7z archives, audio and video.
  • Each file can be as large as the board's plan allows (25 MB on Free, 2 GB on Pro, 5 GB on a team's boards), up to 4 GB from the command line. A file over 8 MB goes straight to Listspace's file storage, sent from your disk. For a bigger file, drag it onto the item in Listspace.
  • Every file is checked before the first one is sent, so a typo in one name uploads nothing.
  • A whole batch goes through. Your AI may send up to 25 files in one go, for the same item or for different ones, and an account may send 200 files or 10 GB an hour. If your AI reaches that, Listspace says when the next upload is allowed, for example after 14:32 UTC, and your AI can wait until then.

Without the command line

An agent connected over MCP can also ask Listspace for an upload link: a one-time address for one item. It sends the file with a single curl command, so nothing has to be set up on your computer. The link works once and for 10 minutes for a file up to 8 MB, and the same level rule applies. For a larger file, up to the plan's size and 4 GB, your AI tells Listspace the file's size first: it then sends the file straight to file storage with one curl command and finishes the upload with a second one. With one request your AI can ask for the links of up to 25 files, for several items at once. The file shows on the item as added by your AI, and your AI gets a checksum (or for a large file, the size that arrived) back to confirm the file arrived intact.

The same file or picture in a second place

Your AI does not need to upload a file twice. A file that is already on one item can be copied to another item of the same board without sending it again: it counts against your storage like any file, but not against the upload limit. Your AI can also put a picture from an item's files into the text of an item, for example an overview with the screenshots of other items. The picture is stored in that text the way a picture you paste there is. It needs level 4 (Act) or higher, and both items must be on the same board.

In ChatGPT

Put the file in the ChatGPT chat and ask, for example: Attach this PDF to the Onboarding item on my Website board. ChatGPT hands the file to Listspace, which downloads it from ChatGPT and stores a copy on the item. Several files work too, one after the other. Each file can be as large as the board's plan allows, and the board needs level 4 (Act), as for any file.

If ChatGPT says it could not pass the file on, which can happen in the ChatGPT phone apps, attach it again in ChatGPT on the web or in the desktop app, or drop it on the item in Listspace.

In Claude

Claude on claude.ai and in the desktop app may not pass files from the chat on to connectors. If the file does not arrive, drop it on the item in Listspace instead, see Files and images.

Claude on claude.ai can upload a file to Listspace only when listspace.app is on its list of allowed websites. Open Settings, then Capabilities. Under Create and edit files, turn on Use the internet while making files. Next to Allowed websites, click Manage, then Add a website, and add listspace.app. For a file over 8 MB, also add *.r2.cloudflarestorage.com, the file storage the upload goes to. If Claude says the upload got a 403 error, this setting is the cause.

In any chat app, your AI can attach a file that is on the web when you give it the link.

Your AI can also write a document and attach it as a PDF, a Word file or markdown: "write up the quote for Sara and attach it as a PDF". Listspace makes the file from the text, so this works in chat apps too. It can also turn the item's own description or document into a file: "attach this document as a Word file". It needs level 4 (Act) on the board, as for any file.

Next: Two-step sign-in and recovery codes

Still stuck? Write to hello@listspace.app and a person will answer.