Attaching files and images
How to attach files and images to a task, from the web app or the CLI.
CodeHerder gives you two ways to add files to a task: file attachments sit alongside the task as downloadable files in the Attachments section, and inline content is embedded directly into task text fields when you drop or paste a file there. The two overlap: when you drop or paste a file into a text field on a saved task, CodeHerder uploads it as a task attachment and the file also appears in the Attachments section.
Members of the task’s workspace, and members of a parent group, can open its attachments. A member of only a child workspace cannot. Agents are narrower: an agent working on a task reads only that task’s own attachments, including images you pasted into the task’s text. Attach a file to the task whose agent needs it.
File attachments
Every task has an Attachments section on its detail page in the web app. Use it to attach supporting files — screenshots, specs, logs, or any other reference material.
To attach a file:
- Open the task detail page.
- Find the Attachments section.
- Click Attach file and choose a file from your computer.
CodeHerder uploads the file and adds it to the list. Any file type is accepted. The maximum file size is 50 MB, and CodeHerder refuses an empty file. This picker takes one file at a time — drop or paste files instead (see below) if you want to add several at once.
Each row in the list shows the file name and size. For a type your browser can display (images, video, audio, PDFs, and HTML files), click the row to preview it without downloading it. For an image, the preview has zoom out, zoom in, and Fit buttons. The +, -, and 0 keys do the same. The preview also has a Download button. If the file can’t render, the preview tells you to download it instead. Any other row is download-only.
HTML files
An HTML file of up to 2 MB opens in a preview that runs it. Scripts and form controls work. CodeHerder runs the file in an isolated frame on a separate origin. The file cannot read your session, send network requests, or change the page around it. The preview has a Full screen button and a Download button.
The isolated frame blocks all external loads, such as web fonts and CDN scripts. Make the file self-contained: put its styles, scripts, and images inside the file. An HTML file over 2 MB stays download-only, and its row says why.
A link to an HTML attachment in a description or comment opens the same preview when the link text ends in .html.
From the list you can also:
- Click Download to save a copy of the file to your computer.
- Click Delete to remove the attachment. CodeHerder asks you to confirm first. Only the person who uploaded the file or a workspace admin can delete it. See Deleting an attachment below for what stays visible after you delete.
Adding files and images inline
Text fields in the web app accept files dropped or pasted directly in. Where the task is already saved, you can drop or paste any file type: the description, a new comment, custom text fields, and the reason when you reopen a task. Only PNG, JPEG, GIF, and WebP count as images. Other formats, such as SVG, are treated like any other file.
Some places accept images only: editing a comment you’ve already posted, custom text fields on the new-task form, and Markdown editors outside a task. In those places a pasted image still displays inline but never joins the Attachments section. A non-image file shows the message “File uploads require a task — save the task first, then attach files.” Add files while writing the comment the first time, or use the Attachments section instead.
To paste a file: Copy a file or image to your clipboard, click inside a text field, then press Ctrl+V (or Cmd+V on macOS).
To drag a file: Drag one or more files from your file manager and drop them onto a text field.
You can drop or paste multiple files at once. CodeHerder inserts a link for each one right away and uploads it in the background, so you can keep writing while the upload finishes. (The new-task form is the exception for non-image files; see below.) An image shows inline as soon as its upload completes; other files stay as a download link the whole time. If CodeHerder refuses an upload outright, because the file is too large or an unsupported type, it removes the link and shows an error. If the transfer later fails on an upload it did accept, the link stays in place, and a warning tells you it won’t load until you attach the file again.
How a file appears in the rendered text depends on its type:
- Images (PNG, JPEG, GIF, WebP) are rendered inline as images.
- All other file types appear as a chip with a file-type icon and the file name. Click the chip to download the file. If an inline image never loads, the text shows “[image unavailable]”.
On a saved task, a file you drop or paste into a text field is also uploaded as a task attachment and appears in the task’s Attachments section — so it is accessible from both places. The size limit is the same as any other attachment: 50 MB.
When creating a new task, a non-image file you drop or paste into the Description is held until you submit the form. CodeHerder then uploads it, up to 50 MB, and it joins the new task’s Attachments section. An image works differently: it uploads right away, but while the task doesn’t exist yet it’s held to a smaller 10 MB limit. CodeHerder adopts it as a regular attachment once the task is created. If a non-image upload fails when you submit, you get no error and its link stays broken. After you create the task, check the Attachments section and attach the file again if it’s missing. Custom text fields on the new-task form work differently: they can’t stage a file before the task exists, so dropping a non-image file there fails with an error asking you to save the task first. An image dropped there still uploads and displays inline, but it doesn’t join the Attachments section — only Description images do that.
Deleting an attachment
Deleting an attachment removes the file, and any link to it — a /files/... or /img/... reference in a text field — breaks. There’s one exception: an image that CodeHerder adopted from something you pasted or dropped inline keeps its content even after you delete the attachment row, so the inline image keeps showing. This covers an image added with --embed from the CLI, and an image pasted or dropped into the Description while creating a new task. An image you paste into an already-saved task’s text field doesn’t get this treatment — deleting that attachment breaks its inline copy too.
The Delete dialog in the web app says the file is permanently removed. That is true of the attachment row, but an adopted inline image keeps showing as described above.
Only the person who uploaded an attachment or a workspace admin can delete it. For anyone else the delete fails with a not-found error, even though the app still shows the Delete button. An agent in a task session can delete only on its own task.
Run ch task attachments <taskId> first to check what you’re about to remove.
Managing attachments from the CLI
The canonical spelling is the nested ch task attachments scope — list, show, create, and delete cover everything; there is no separate “image” concept, everything is an attachment. Each op keeps its older, flat alias too (ch task attach for create, ch task attachment for show), delete also answers to rm, and dropping the op entirely still lists — see Managing a record’s child collections for how the two spellings relate. Like most ch task commands, each one defaults its task argument from CH_TASK_ID when you omit it — see Agents and the CLI.
Upload a file:
ch task attachments create <taskId> <file>
This uploads the local file as a task attachment and prints its ID, then its download URL. Use --name <n> to store it under a different name than the local file’s. The file can be up to 50 MB. (ch task attach <taskId> <file> is the same command under its older name.)
To embed an image inline (rather than attach it as a separate file), add --embed; the command uploads it, adopts it as a task attachment so it also appears in ch task attachments, and prints a paste-ready inline-image markdown snippet you can drop straight into a description or comment, followed by the attachment’s own ID. --embed ignores --name — CodeHerder assigns the embedded image its own file name automatically. It only accepts PNG, JPEG, GIF, or WebP, capped at 10 MB. For a larger image, attach it as a regular file instead (up to 50 MB) and link to it, or open the task and paste the image directly into a comment.
To attach a UI prototype instead of a regular file, add --prototype. This only accepts a single .html file, capped at 2 MB, and it’s mutually exclusive with --embed — pick one or the other. On success, the command prints the attachment’s ID and download URL, then a follow-up command, ch task edit <taskId> --prototype <id>, which sets the prototype as the task’s active one; this only works on a task whose type has a prototype field, so it won’t apply to every task. A prototype shows in the Attachments list like any other HTML file, and the task’s prototype field shows it in a viewer. You can upload a prototype only from the CLI. See The prototype kit for how to build a prototype file.
List a task’s attachments:
ch task attachments <taskId>
# same as: ch task attachments list <taskId>
This lists every uploaded attachment together with any images embedded in the task’s description or custom text fields that haven’t already been adopted as an attachment. Each row shows KIND, ID, SIZE, NAME, and URL — KIND reads attachment for an uploaded file, embedded for an image found in the task’s text that isn’t an attachment yet, or prototype for a file uploaded with --prototype. If the task has no attachments, a message is printed to indicate that. The list is paged — add --limit/--cursor to work through a task with a lot of attachments; see Paging through long lists.
For machine-readable output:
ch task attachments <taskId> --json
Download an attachment to a local file:
ch task attachments show <taskId> <id>
Pass the ID shown by ch task attachments (a bare UUID, a /files/<uuid> token, or a /img/<uuid> token). CodeHerder saves the file to a temporary file and prints the path so you can open or process it immediately. (ch task attachment <taskId> <id> is the same command under its older name.)
To save to a specific path instead of a temporary file:
ch task attachments show <taskId> <id> --out ./screenshot.png
Delete an attachment:
ch task attachments delete <taskId> <id>
In an interactive terminal, the command asks Permanently delete attachment <id>? [y/N]. Answer no and it prints “Aborted — nothing was deleted.” When stdin is not interactive, such as in a script, add --yes. Without it the command refuses and makes no request. Only the uploader or a workspace admin can delete. See Deleting an attachment above for what happens to inline copies.
For writing task descriptions and acceptance criteria, see Writing tasks an agent can build. For the full ch task command reference, see Agents and the CLI.
Last updated