Organizing artifacts

Artifacts pile up fast when an agent publishes every draft. Folders keep a workspace readable, and your agent can do the filing.

Your agent files as it publishes

The artifact-cafe skill picks a folder before it publishes, so you don't name a destination every time. Ask for a tidy-up and it sorts what's already there:

publish this into the design specs folder
what's in my acme workspace?
organize my artifacts

What the skill does on its own:

• Lists the workspace's folders before a first publish, then matches on meaning. A "Specs" folder takes a new spec even when no words overlap.
• Reuses an existing folder before it creates one, and never creates a folder to hold a single artifact. A genuine one-off stays unfiled instead of landing in a bad match or a "Misc" bucket.
• Asks before it puts anything in a public folder, and reports every visibility change a move causes.
• Reads the whole library in one call when you ask it to organize. list --workspace <handle> --json returns each artifact with its folderId plus the folder list, and the skill answers with a plan: folders to create, what moves where, which moves change who can open the link. It waits for your approval before touching anything.

Folder commands need the Node CLI and a signed-in account. The zero-Node bash fallback still publishes, but it can't file. Renaming and deleting folders stay in the dashboard; the CLI ships no destructive folder commands.

The folder model

Every workspace holds a flat list of folders, Personal included. There's no nesting. A folder is either public (anyone can see the artifacts in it) or workspace (members only).

A folder's visibility becomes the default for the artifacts you place in it, so you sort once instead of setting each artifact by hand. Public folders carry a permalink at {handle}.artifact.cafe/f/{folder} that lists their public artifacts. Rename the folder and that link changes.

You create, rename, re-scope, and delete folders in the dashboard: owner or admin in a team workspace, always yours in Personal. Changing a folder's visibility offers to cascade the change to the artifacts already inside. Skip the cascade and only later placements pick up the new default.

Folders and artifacts can both carry an emoji instead of the default icon — set it beside the name in folder settings, or beside the title in an artifact's settings. Setting an artifact's icon takes the same rights as renaming it: a workspace admin, or whoever published it.

File at publish time

npx artifact-cafe@latest folders --workspace acme --json
npx artifact-cafe@latest publish . --workspace acme --folder specs

--folder takes an exact folder name (case-sensitive) or a folder id. The CLI stores the resolved placement in .artifactcafe/config.json, so a later bare publish puts the next version in the same folder.

folders create "<name>" --workspace acme adds one from the terminal. It refuses a name the workspace already uses, since two folders sharing a name break --folder <name> addressing.

Re-file later

npx artifact-cafe@latest move --folder "Design specs"
npx artifact-cafe@latest move --artifact art_x --unfiled

move changes the placement and nothing else: no new version, and the review link, version history, and comments stay put. In the dashboard, drag a row onto a folder or use the row's move menu. Sign in with artifact-cafe login or pass --api-key, since a publish token can't re-file.

Placement decides who can open the link

An artifact takes its folder's visibility when the person placing it can set visibility: a workspace admin, or whoever published the artifact. Move something into a public folder and you publish it.

• New artifacts start unlisted, so most first placements change visibility.
• The dashboard confirms a move that widens an artifact to public. A move that narrows it to members-only goes through without a prompt.
• The CLI reports previousVisibility and visibility in --json output.
• An unfiled artifact keeps the visibility it already has.

Artifact visibility covers what each level means.

See also

Workspaces for members and roles, Publishing concepts for artifacts and versions, and the CLI reference for folders, move, and list.