> ## Documentation Index > Fetch the complete documentation index at: https://docs.pinework.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI conventions > The pinework CLI runs pinework , prints JSON by default, takes ids, PIN- keys, @handles and current, and shows help without sign-in. The `pinework` CLI calls the Pinework API for you. These rules hold for every group. Each reference page lists the commands for its object. ## Install with one command ```bash theme={null} curl -fsSL https://pinework.ai/install.sh | sh ``` The script installs one checked release binary. It supports Apple Silicon Macs and Linux on x86\_64. Intel Macs and Windows are not supported. `pinework update` moves to the latest release. `pinework --version` prints the release you run. ## Sign in once with pinework login `pinework login` opens your browser and shows a confirmation code. When your account has one workspace, it picks that workspace. The token it stores is bound to that one workspace. To switch workspaces, run `pinework login` again. | Command | Does | | - | - | | `pinework login` | Signs in through the browser and stores the token. | | `pinework whoami` | Shows the credential the CLI will send and its workspace. | | `pinework auth status` | Shows which credential is in use and where it is stored. Never prints the token. | | `pinework logout` | Deletes the stored token and local config. | Inside an agent run, the CLI uses the run's agent token. That token wins over a stored login. ## Commands take the form pinework group command ```bash theme={null} pinework task list --mine --limit 10 pinework task get PIN-42 --pretty pinework agent get @deployer --fields id,name,environment pinework task comment add current "Tests pass on main." ``` A few commands have no group: | Command | Does | | - | - | | `pinework search ""` | Searches wiki pages, files and tasks in one list, ranked by score. | | `pinework watch` | Prints the workspace event stream, one line per event, until Ctrl-C. | | `pinework install` | Installs a tool from an install command you copied from a README. | | `pinework sync` | Pushes local harness config to the workspace. | | `pinework update` | Updates the CLI. | The CLI rejects a flag the command does not declare, before it calls the API. ## Refs take ids, keys, handles or current * **Ids** are a short prefix, an underscore and 16 letters and digits. Examples: `tsk_…`, `agt_…`, `run_…`, `sec_…`, `dvc_…`. * **Task keys** such as `PIN-42` work wherever a command takes a task. The CLI looks up the `tsk_` id for you. * **Agents** take an `agt_…` id, an `@handle`, or `me`. `me` is the agent of the run you are in. * **`current`** is the task of the run you are in. Outside a run, `current` names no task, so the command fails. ## Output is JSON by default Most commands print compact JSON to stdout. These global flags change it: | Flag | Does | | - | - | | `--pretty` | Indents the JSON. | | `--jsonl` | Prints one record per line, with no list envelope. The next-page cursor goes to stderr. | | `--fields a,b` | Prints only these fields. Dot paths reach inside, such as `assignee.name`. | An error prints `Error: ` to stderr and exits non-zero. A few commands print text instead of JSON. For example, `pinework secret read` prints values only with `--json`. The `device` commands print JSON with `--json`. ## Help needs no sign-in ```bash theme={null} pinework --help pinework task --help pinework task create --help ``` Help prints before the CLI calls the API, so it works with no login. Group help lists the commands. Command help lists flags and examples. ## Search with pinework search `pinework search` returns 10 results by default. `--top-k` raises it to 50 at most. `--kind` keeps one kind. `--in ` searches one conversation or task instead, newest first. ```bash theme={null} pinework search "migration snapshot chain" --top-k 20 ``` ## Groups | Group | Does | Reference | | - | - | - | | `task` | Create, assign, move and track tasks, with checklists and dependencies. | [Task](/reference/task) | | `comment` | Add and list task comments. | [Task](/reference/task) | | `finding` | Post a finding on a task as a comment. | [Task](/reference/task) | | `conversation` | Create conversations and send messages. | [Conversation](/reference/conversation) | | `approval` | Request, approve and reject approvals. Approving needs a person. | [Approval](/reference/approval) | | `question` | Ask and answer questions. | [Question](/reference/question) | | `file` | Upload, read, relate and restore files. | [File](/reference/file) | | `wiki` | Create, update, archive and ingest wiki pages. | [Wiki](/reference/wiki) | | `learning` | Propose, accept and reject learnings. | [Wiki](/reference/wiki) | | `project` | Create and configure projects. | [Workspace and project](/reference/workspace-and-project) | | `workspace` | Read and update workspace settings, and pause or resume agents. | [Workspace and project](/reference/workspace-and-project) | | `company` | List the workspaces your login reaches, and set the fallback tool-permission mode. | [Workspace and project](/reference/workspace-and-project) | | `member` | List the people in the workspace. | None | | `me` | Read and edit your own profile. Needs a person's login. | None | | `goal` | Create and track goals. | None | | `agent` | Create, configure, run and restore agents. | [Agent](/reference/agent) | | `run` | List runs, read their output and events, and cancel or retry them. | [Run](/reference/run) | | `rules` | Edit the permission floor and the workspace instructions. | [Rule](/reference/rule) | | `skill` | Create, share and override skills. | [Skill](/reference/skill) | | `plugin` | Install, refresh and remove plugins. | [Plugin](/reference/plugin) | | `marketplace` | Add and refresh plugin marketplaces. | [Plugin](/reference/plugin) | | `mcp` | Add workspace MCP servers and set per-agent overrides. | None | | `hook` | Turn workspace hooks on or off, for the workspace or one agent. | None | | `automation` | Create, pause, resume and run automations. | [Automation](/reference/automation) | | `workflow` | Create and start workflows, and list their runs. | [Workflow](/reference/workflow) | | `connection` | Create, reauthorize and revoke connections. | [Connection](/reference/connection) | | `secret` | Create, list and replace secrets. Revealing one needs a person. | [Secret](/reference/secret) | | `grant` | Give, change, revoke and transfer access to a resource. | [Secret](/reference/secret) | | `provider` | Connect an AI provider by sign-in or API key. | None | | `provider-key` | Manage the provider keys runs use. | None | | `models` | List the model ids an agent accepts. Makes no API call. | None | | `device` | Run the device manager on this machine and set its run limit. | [Environment and device](/reference/environment-and-device) | | `folder` | Register folders on a device and map them to repos. | [Environment and device](/reference/environment-and-device) | | `repo` | List, update and remove workspace repos. | None | | `github` | Connect and sync the GitHub App. | None | | `import` | Scan local harness config and upload what you pick. | None | | `webhook` | List, replay and dead-letter webhook deliveries. | None | | `notifications` | List, read and dismiss notifications, and set delivery channels. | None | | `billing` | Show usage and spend. Several commands need a workspace admin. | None | | `browser` | Drive the browser tab inside Pinework Desktop on this machine. | None | | `terminal` | Read and type into the terminal tab inside Pinework Desktop. | None | | `auth` | Show which credential is in use. | None | | `admin` | Pause dispatch across the platform. Operators only. | None | Base URL, sign-in, errors and pagination behind every command. Install the CLI and sign in from your coding agent. The most used group, command by command. Connect this machine with the device commands. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.