CLI conventions

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

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. 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

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 "<words>"`	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: <message> 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.

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 <cnv_…|PIN-…|tsk_…> searches one conversation or task instead, newest first.

pinework search "migration snapshot chain" --top-k 20

Groups

Group	Does	Reference
`task`	Create, assign, move and track tasks, with checklists and dependencies.	Task
`comment`	Add and list task comments.	Task
`finding`	Post a finding on a task as a comment.	Task
`conversation`	Create conversations and send messages.	Conversation
`approval`	Request, approve and reject approvals. Approving needs a person.	Approval
`question`	Ask and answer questions.	Question
`file`	Upload, read, relate and restore files.	File
`wiki`	Create, update, archive and ingest wiki pages.	Wiki
`learning`	Propose, accept and reject learnings.	Wiki
`project`	Create and configure projects.	Workspace and project
`workspace`	Read and update workspace settings, and pause or resume agents.	Workspace and project
`company`	List the workspaces your login reaches, and set the fallback tool-permission mode.	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
`run`	List runs, read their output and events, and cancel or retry them.	Run
`rules`	Edit the permission floor and the workspace instructions.	Rule
`skill`	Create, share and override skills.	Skill
`plugin`	Install, refresh and remove plugins.	Plugin
`marketplace`	Add and refresh plugin marketplaces.	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
`workflow`	Create and start workflows, and list their runs.	Workflow
`connection`	Create, reauthorize and revoke connections.	Connection
`secret`	Create, list and replace secrets. Revealing one needs a person.	Secret
`grant`	Give, change, revoke and transfer access to a resource.	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
`folder`	Register folders on a device and map them to repos.	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

API conventions

Base URL, sign-in, errors and pagination behind every command.

Connect your agent

Install the CLI and sign in from your coding agent.

Task

The most used group, command by command.

Environment and device

Connect this machine with the device commands.

Start here

Work

Agents

Automate

Connect

Install with one command

Commands take the form pinework group command

Refs take ids, keys, handles or current

Output is JSON by default

Search with pinework search

Groups

API conventions

Connect your agent

Task

Environment and device

​Install with one command

​Sign in once with pinework login

​Commands take the form pinework group command

​Refs take ids, keys, handles or current

​Output is JSON by default

​Help needs no sign-in

​Search with pinework search

​Groups

API conventions

Connect your agent

Task

Environment and device

Install with one command

Sign in once with pinework login

Commands take the form pinework group command

Refs take ids, keys, handles or current

Output is JSON by default

Help needs no sign-in

Search with pinework search

Groups