# Stuff from the terminal

Install with Node.js 24 or newer:

```sh
npm install --global https://stuff.ac/downloads/stuff-ac-cli-0.4.0.tgz
stuff --help
```

No repository checkout is needed. The same package works on macOS, Linux and Windows with Node and npm. This is a download hosted by Stuff, not a claim that the package is published on the npm registry. Release checksum and npm integrity: <https://stuff.ac/downloads/cli.json>.

Create a dedicated connection in [Stuff → Connections](https://stuff.ac/agents). Choose only the spaces and permissions it needs. Store its key as `STUFF_API_KEY` in your terminal or agent's private environment; don't paste it into a shared file, command argument or chat. Existing keys work unchanged.

```sh
stuff check
stuff request GET /spaces
stuff context stuff:space:YOUR_SPACE_ID
stuff ls stuff:space:YOUR_SPACE_ID
stuff read stuff:item:YOUR_FILE_ID
stuff diff stuff:item:YOUR_FILE_ID 1 2
```

`stuff check` exercises the installed command, HTTPS authentication and current permissions without writing files. A revoked or expired key fails. The Connections page's “Check access” checks the grant from your signed-in account; it cannot prove another assistant is configured correctly.

Commands return JSON for agents and scripts. A reference or URL is an identifier, not a credential. The current user role and connection scope always apply. File history and diffs require editor access; a read-only connection can inspect history if its user has editor access.

## Local MCP clients

Use command `stuff` with argument `mcp` and supply `STUFF_API_KEY` through the client's secure environment configuration. If that app can't find global commands, use the absolute path printed by `command -v stuff` (macOS/Linux) or `where stuff` (Windows). Remote clients can use <https://stuff.ac/mcp> with OAuth instead, without installing a CLI.

Ask the assistant: “Run connection_check, list my spaces, read one Markdown file, and return its Stuff link. Don't change anything yet.”

## Editing and sync

See the [filesystem guide](https://stuff.ac/connect/filesystem.md) for ranged reads, exact search, targeted edits, batch operations and folder pull/push. Writes use expected versions; conflicts preserve local drafts. New files use stable retry keys. Folder push does not delete remote files when you delete local files.

Set `STUFF_CLIENT` and `STUFF_ACTOR_TYPE=agent` for an assistant, or `automation` for a script. Supply `STUFF_MODEL` and `STUFF_MODEL_PROVIDER` only when the actual model is known. Per-tool MCP attribution overrides environment defaults. Connection details can remember a client name and source type, but never a default model. See [edit attribution](https://stuff.ac/connect/attribution.md).

To use a local development server, set `STUFF_ORIGIN` to its exact localhost origin. Production origins must use HTTPS. To upgrade, install the versioned download linked from Stuff's connection page. To remove the command: `npm uninstall --global @stuff-ac/cli`.

## Latest content

CLI 0.4.1 adds `stuff feed --limit 20`. It returns current file cards from owned and joined spaces in reverse chronological order. Continue with `stuff feed --cursor '<nextCursor>'`; selected connection scopes still apply. The stdio MCP server exposes the same `get_feed` tool. A generic `stuff request GET /feed` also works.