---
title: "Command line"
description: "Install the Jsonify CLI, sign in with a workspace key, and run pipelines, watch runs, export datasets and ask Jason for work from a terminal or a job."
url: "https://www.jsonify.com/docs/integrations/cli"
---

[Documentation](https://www.jsonify.com/docs/) Filter pages

## Getting started

*   [What is Jsonify?](https://www.jsonify.com/docs/)
*   [How pipelines work](https://www.jsonify.com/docs/how-jsonify-works)
*   [Your first pipeline](https://www.jsonify.com/docs/getting-started/first-pipeline)
*   [Workspaces](https://www.jsonify.com/docs/getting-started/workspaces)
*   [Glossary](https://www.jsonify.com/docs/getting-started/glossary)

## Tutorials

*   [Track the Hacker News front page](https://www.jsonify.com/docs/tutorials/hacker-news)
*   [Monitor prices across retailers](https://www.jsonify.com/docs/tutorials/price-monitoring)
*   [Get a Slack alert when a price drops](https://www.jsonify.com/docs/tutorials/slack-price-alert)
*   [Use a dataset from your agent](https://www.jsonify.com/docs/tutorials/agent-query)

## Jason

*   [Chatting with Jason](https://www.jsonify.com/docs/jason/chat)
*   [Changing a pipeline](https://www.jsonify.com/docs/jason/changing-a-pipeline)
*   [Agents, workers and repairs](https://www.jsonify.com/docs/data-agents)

## Pipelines

*   [The pipeline page](https://www.jsonify.com/docs/pipelines/overview)
*   [Statement of work and steps](https://www.jsonify.com/docs/pipelines/statement-of-work)
*   [Inputs and parameters](https://www.jsonify.com/docs/pipelines/inputs)
*   [Settings reference](https://www.jsonify.com/docs/pipelines/settings)
*   [Versions and changelog](https://www.jsonify.com/docs/pipelines/versions)

## Runs

*   [Running a pipeline](https://www.jsonify.com/docs/runs/running)
*   [Scheduling](https://www.jsonify.com/docs/runs/scheduling)
*   [Run detail](https://www.jsonify.com/docs/runs/run-detail)
*   [Run lifecycle](https://www.jsonify.com/docs/runs/lifecycle)
*   [Verification and repair](https://www.jsonify.com/docs/runs/verification-and-repair)

## Datasets

*   [Dataset pages](https://www.jsonify.com/docs/datasets/overview)
*   [Versions](https://www.jsonify.com/docs/datasets/versions)
*   [Query and export](https://www.jsonify.com/docs/datasets/query-and-export)
*   [Row detail and provenance](https://www.jsonify.com/docs/datasets/provenance)
*   [Sharing](https://www.jsonify.com/docs/datasets/sharing)

## Analytics

*   [Dashboards](https://www.jsonify.com/docs/analytics/dashboards)
*   [Newsletters](https://www.jsonify.com/docs/analytics/newsletters)

## Alerts

*   [Alert rules](https://www.jsonify.com/docs/alerts/rules)
*   [Alert history and notifications](https://www.jsonify.com/docs/alerts/history)

## Integrations

*   [Integrations overview](https://www.jsonify.com/docs/integrations/overview)
*   [Slack and email](https://www.jsonify.com/docs/integrations/slack-and-email)
*   [Sheets, warehouses and webhooks](https://www.jsonify.com/docs/integrations/destinations)
*   [Ingest and serve API](https://www.jsonify.com/docs/integrations/api)
*   [Connect your agent (MCP)](https://www.jsonify.com/docs/integrations/mcp)
*   [Command line](https://www.jsonify.com/docs/integrations/cli)

## Workspace and account

*   [Workspace settings](https://www.jsonify.com/docs/workspace/settings)
*   [Team](https://www.jsonify.com/docs/workspace/team)
*   [Billing and usage](https://www.jsonify.com/docs/workspace/billing)
*   [Data retention](https://www.jsonify.com/docs/workspace/data-retention)

## Plans

*   [Radar or Benchmark? Enterprise](https://www.jsonify.com/docs/radar-vs-benchmark)
*   [Row pricing and managed service](https://www.jsonify.com/docs/pricing-model)

## More

*   [Connect your agent](https://www.jsonify.com/connect)
*   [Pricing](https://www.jsonify.com/pricing)
*   [Contact support](https://www.jsonify.com/contact)

[Docs](https://www.jsonify.com/docs/)/Integrations

# Command line

Install the Jsonify CLI, sign in with a workspace key, and run pipelines, watch runs, export datasets and ask Jason for work from a terminal or a job.

The Jsonify CLI is a single command, `jsonify`, that talks to one workspace over HTTPS with a key you create in Jsonify. It is built for people at a terminal and for automation and AI agents alike: every command prints one JSON object, errors go to stderr as JSON, and exit codes are stable.

Platform

macOS (Windows is coming soon)

Needs

Nothing to install first; the installer checks your Mac

Access

Read, or Operator

Output

JSON; JSON Lines for watch commands

1.  **Create a key**Integrations, Jsonify CLI
2.  **Install**one command
3.  **Sign in**jsonify auth login
4.  **Use**pipelines, runs, datasets, Jason

Four steps from nothing to a working terminal.

## Create a key

A CLI key is an integration. Each key belongs to one workspace and has one access level, and you can have as many as you need.

1.  **Add integration** and choose **Jsonify CLI** under Developer. The dialog is titled **Connect Jsonify CLI**.
2.  **Label it.** Name the person or agent that will use it, for example “Acme data agent”. Use separate integrations when people or agents need separate keys.
3.  **Choose the access.** **Read** or **Operator**, described below.
4.  **Create key.** The next screen, **Jsonify CLI is ready**, shows the key once, followed by the three commands to install, sign in and verify.
5.  **Copy the key now.** Jsonify does not show it again. If it is lost, rotate the credential from the integration’s detail page.

![The Connect Jsonify CLI dialog with the Label field and the Read and Operator access cards](/assets/images/product/integrations-cli-setup.png)

Choose the access level before creating the key. It can be changed later by rotating.

| Option | Values | Default | What it does |
| --- | --- | --- | --- |
| Label | Text | “Jsonify CLI” | How the integration appears on the Integrations page, and the name shown as the author of any chat this key starts |
| Access | Read / Operator | Read | What the key may do |

### Read or Operator

| Access | What the key can do |
| --- | --- |
| Read | Inspect workspace context, pipelines, versions and runs; search; read usage; read, query and export dataset rows; read Jason chats and their events |
| Operator | Everything in Read, plus start and cancel runs, rerun rows, change schedules, fetch caching and automatic repair, and start, message, stop or archive Jason chats |

No key can edit, approve or activate a pipeline version directly. Changes go through Jason’s normal build, review and activation, which an Operator key can request and follow.

> Give a key the least access that does the job. A reporting job needs Read; an agent that runs pipelines needs Operator. Keys never expire on their own; they stop working when rotated, revoked, when the integration is deleted, or when the person who created them leaves the organisation.

## Install

Run the installer shown on the setup screen:

```
curl -fsSL https://factory.jsonify.com/cli/install.sh | sh
```

It verifies the download’s checksum and installs `~/.local/bin/jsonify`. It does not use `sudo` and does not edit your shell profile; if `~/.local/bin` is not on your `PATH`, it prints the line to add. Then:

```
jsonify --version
```

The CLI keeps itself current: when a newer release is available it updates itself once in the background, and `jsonify --update` checks and updates on demand.

## Sign in

Use the second command from the setup screen. `--profile` names this workspace on your machine; use the workspace’s name or slug.

```
jsonify auth login --profile acme --api-url https://factory.jsonify.com
```

It asks for the key and does not echo it. To supply the key from automation without putting it in shell history:

```
printf '%s' "$JSONIFY_KEY" | jsonify auth login --profile acme --api-url https://factory.jsonify.com --stdin
```

Confirm the workspace and access level:

```
jsonify context
```

### Profiles

One profile per workspace. The profile you signed in with last is the default.

| Command | What it does |
| --- | --- |
| jsonify auth list | Lists profiles and marks the default |
| jsonify auth default --profile NAME | Makes a profile the default |
| jsonify auth status --profile NAME | Checks one profile’s key still works |
| jsonify auth logout --profile NAME | Removes a profile |
| jsonify --profile NAME <command> | Uses a profile for one command |

For a one-off job, environment variables override stored profiles and are never saved: `JSONIFY_API_KEY` and `JSONIFY_API_URL`.

> Treat the key like a password. Do not pass it as a command argument, commit it, paste it into an agent’s instructions, or log it.

## Output

*   **One JSON object per command.** In a terminal it is indented and coloured; when piped or redirected it is compact, one object, no colour. Force either with `--pretty` or `--compact` before the command; `--color auto|always|never` controls colour.
*   **JSON Lines for watch commands.** `runs watch` and `jason watch` print one compact object per line as things change, with a heartbeat about every thirty seconds, and stop when the run or turn finishes.
*   **Errors on stderr as JSON**, with a short error identifier, a `message`, the HTTP status and a `request_id` to quote to support.
*   **Lists** carry `items`, a `next_cursor` or `next_before` when there is another page, and `truncated`.
*   **Stable identifiers and links.** Every pipeline, run, dataset and chat comes with its public identifier and its Jsonify URL. Timestamps are Unix seconds with an ISO 8601 twin (`created_at_iso`).

| Exit status | Meaning |
| --- | --- |
| 0 | Success |
| 2 | Local usage, configuration or file problem |
| 3 | Sign-in or permission failure |
| 4 | Jsonify rejected the request |
| 5 | Network or server failure |
| 6 | A watched run failed or was cancelled |

## Command reference

Every command has `--help` with the exact options installed on your machine. This table is the map.

### Workspace

| Command | What it does |
| --- | --- |
| jsonify context | The workspace, access level, billing allowance and rows remaining |
| jsonify search "text" | Finds pipelines, datasets, runs and chats by name. Add --dataset-rows to also search inside dataset values (three characters or more) |
| jsonify usage [--days N] [--pipeline ID] | Rows used and remaining, and run activity for the period |
| jsonify ask "task" [--context pipeline:ID] [--attach FILE] [--notify EMAIL] [--wait] | Sends Jason a task, optionally attached to a pipeline, dataset or workspace, and optionally waits for the reply. Operator |

### Pipelines

| Command | What it does |
| --- | --- |
| jsonify pipelines list [--limit N] | Pipelines with status, version and schedule |
| jsonify pipelines get ID [--version N] [--full-inputs] | One pipeline: what it collects, parameters, inputs, outputs |
| jsonify pipelines inspect ID | The same plus the latest run, per-output counts and a failure summary |
| jsonify pipelines versions ID | The version history with changelogs |
| jsonify pipelines run ID [--version N] [--row-limit N \\| --uncapped] [--param k=v] [--input NAME=DATASET@VERSION/TABLE] [--idempotency-key KEY] [--wait] | Starts a run. Operator |
| jsonify pipelines schedule ID hourly\\|daily\\|weekly\\|off [--time HH:MM] [--day mon] [--timezone TZ] | Sets the schedule. Operator |
| jsonify pipelines cache ID <duration\\|off\\|default> | Sets how long fetched pages may be reused, for example 12h or 30d. Operator |
| jsonify pipelines auto-heal ID on\\|off | Turns automatic repair of failed scheduled and webhook runs on or off. Operator |
| jsonify pipelines build "brief" [--notify EMAIL] | Asks Jason to build a new pipeline. Operator |
| jsonify pipelines change ID "request" [--notify EMAIL] [--wait] | Asks Jason to change a pipeline; --wait follows it through review and activation. Operator |

Pipeline identifiers accept the short identifier, the identifier with its slug, or the full Jsonify URL.

### Runs

| Command | What it does |
| --- | --- |
| jsonify runs list [--status …] [--limit N] | Recent runs, newest first |
| jsonify runs get RUN [--samples] [--source-breakdown] | One run: status, timing, outputs and counts. --samples adds five rows per output |
| jsonify runs watch RUN | Follows a run as JSON Lines until it finishes. Exit 6 on failure |
| jsonify runs failures RUN | A summary of the failed and held rows and their reasons |
| jsonify runs activity RUN [--kind event\\|log\\|fetch\\|provenance] [--limit N] | The run’s activity feed |
| jsonify runs logs RUN [--source …] [--level …] [--cursor …] | The run’s logs, filtered and paged |
| jsonify runs steps RUN | Each step with its status and row counts |
| jsonify runs step-data RUN STEP [--offset] [--limit] [--column C] | Rows a completed step produced |
| jsonify runs output RUN --output NAME [--offset] [--limit] | A page of one published output |
| jsonify runs export RUN --output NAME --out FILE [--max-rows N] [--column C] | Writes one output as JSON Lines; 10,000 rows by default |
| jsonify runs provenance RUN --row-id ID | Where one row came from: step, fetch, source page |
| jsonify runs cost RUN | What the run used |
| jsonify runs cache RUN | How much the run reused from cache versus fetched live |
| jsonify runs lineage RUN | The chat, candidate, review and version behind the run |
| jsonify runs cancel RUN | Stops an active run. Operator |
| jsonify runs rerun-rows RUN --input-name N --output O --row-id ID… [--idempotency-key K] | Re-collects up to 100 exact rows. Operator |

### Datasets

| Command | What it does |
| --- | --- |
| jsonify datasets list | Datasets with row counts and versions |
| jsonify datasets get ID | One dataset: worksheets, columns, versions |
| jsonify datasets rows ID [--version N] [--table T] [--offset] [--limit] [--column C] | A page of rows from one version |
| jsonify datasets query --dataset ALIAS=ID[@VERSION][/TABLE]… --sql "…" [--max-rows N] | Read-only SQL across up to 20 datasets, 500 rows |
| jsonify datasets export ID [--version N] [--table T] --format json\\|csv\\|xlsx --out FILE | Writes one version to a file. A workbook always holds every worksheet |

### Deliverables

| Command | What it does |
| --- | --- |
| jsonify deliverables list | Files a pipeline produced, latest version of each |
| jsonify deliverables history ID | Every version of one file |
| jsonify deliverables fetch VERSION_ID --out FILE | Downloads one exact version |
| jsonify deliverables delete ID | Removes the series. Operator |

### Jason

| Command | What it does |
| --- | --- |
| jsonify jason list | Chats in the workspace |
| jsonify jason new "text" [--attach FILE] [--notify EMAIL] | Starts a chat. Operator |
| jsonify jason get SESSION | A chat’s state |
| jsonify jason events SESSION [--after N] | What has happened in a chat, from an event number |
| jsonify jason send SESSION "text" [--notify EMAIL] | Sends a message to a chat. Operator |
| jsonify jason watch SESSION [--after N] | Follows a chat as JSON Lines. --after 0 replays from the start |
| jsonify jason stop SESSION | Stops the running turn. Operator |
| jsonify jason archive SESSION | Archives the chat. Operator |

`--notify EMAIL` on any command that starts a Jason turn sends one email when that turn finishes; Jsonify creates the email channel for you. Chats started from the CLI appear in the workspace’s chat history with a green **CLI** badge and the integration’s label as the author.

### Global options

`--version`, `--guide` (the built-in agent guide, offline), `--docs` (the full reference from your Jsonify origin), `--update`, `--pretty`, `--compact`, `--color`, `--profile NAME`. Put them before the command.

## Typical flows

### Run a pipeline and wait

```
jsonify pipelines run marketpipe03 --row-limit 500 --param region=uk --idempotency-key nightly-2026-09-15 --wait
```

`--wait` follows the run and exits `0` when it completes or `6` when it fails, so a job can branch on it. The idempotency key makes retries safe: repeating the same command with the same key returns the same run instead of starting another. `--param` values that are valid JSON keep their type (`true`, `12`, `"pt"`).

### Watch a run started elsewhere

```
jsonify runs watch mrun00000361
```

One compact JSON line each time the run’s state or evidence changes, a heartbeat line about every thirty seconds, then exit. Reconnects after a dropped connection do not repeat lines you already have.

### Export a dataset

```
jsonify datasets export marketdata02 --format csv --table main --out ./price-observations.csv
jsonify datasets export marketdata02 --version 61 --format xlsx --out ./price-observations-v61.xlsx
```

Exports are rendered on the server and downloaded whole; the CLI refuses to overwrite an existing file unless you add `--force`. To export the rows a particular run produced, before or after it publishes, use `runs export`.

### Ask a question of the data

```
jsonify datasets query \
  --dataset offers=marketdata01 \
  --dataset obs=marketdata02@61 \
  --sql 'SELECT o.retailer, count(*) AS drops FROM obs JOIN offers o ON o.product_url = obs.product_url WHERE obs.change < 0 GROUP BY o.retailer ORDER BY drops DESC' \
  --max-rows 50
```

### Ask Jason and wait for the answer

```
jsonify ask "Why did last night's price promotion run publish 30% fewer rows than usual?" \
  --context pipeline:marketpipe03 --wait
```

```
jsonify pipelines change marketpipe03 "Add the promotion end date as its own column" --notify you@example.com --wait
```

The second command follows the change through Jason’s build, the reviewer’s verdict and activation, and finishes with the new version number.

## Rotate or revoke a key

Open the CLI integration from the Integrations page. Its **Settings** tab shows the credential: its identifier, access, who created it, when it was created, rotated and last used.

*   **Rotate key** issues a new key, shown once, and stops the old one immediately. Choose the access the new key should have in **Access after rotation** first; this is how you move a key from Read to Operator or back. Then run `jsonify auth login` again on each machine that uses it.
*   **Revoke** stops the key immediately and turns the integration **Revoked**. The button becomes **Issue new key**, which is a rotation that brings it back to Live.
*   **Delete integration** (on the **Danger** tab) revokes the key too.

![The CLI credential panel with the install commands, credential facts, the Access after rotation menu and the Rotate key and Revoke buttons](/assets/images/product/integrations-cli-credential.png)

Rotation and revocation both take effect immediately.

## Pointing an AI agent at the CLI

The CLI ships with an operating guide written for agents. It explains the output contract, the exit codes, how to wait for a run or a chat without polling, how to retry safely, and what the CLI deliberately will not do. Have the agent read it before it runs anything else:

```
jsonify --guide
```

The same text is on the integration’s **Overview** tab as **Guide for AI agents**, with **Copy guide** so you can paste it into the instructions file of the project the agent works in, and **Full reference** for the complete command reference. Give the agent its own key with its own label; every chat it starts is then attributed to it in the chat history, and revoking it never affects a person’s key.

> An agent given an Operator key and the guide can carry a whole change on its own: ask Jason for the change with `pipelines change --wait`, run the activated version with `pipelines run --wait`, and export the result with `runs export`. Every step is a normal Jsonify action you can see in the browser.

## Troubleshooting

| Symptom | What to do |
| --- | --- |
| jsonify: command not found | Add ~/.local/bin to PATH as the installer said, then open a new shell |
| The installer says the runtime on the Mac is too old | Update macOS (or its developer tools) and run the installer again |
| “Credential permissions are rejected” | The CLI refuses a loosely permissioned credentials folder. Restore 0700 on ~/.config/jsonify and 0600 on the file inside it, with no symlinks |
| “The key is invalid or revoked” (exit 3) | Check the integration in Jsonify. Rotate if the key was lost, then jsonify auth login again |
| A command needs Operator access | Rotate the integration to Operator, or create a separate Operator integration |
| The installer says “Windows is coming soon.” | The first release is macOS only |

Every request carries a `request_id`; include it from the error JSON when you contact support.

## What’s next

[**Running a pipeline**

What row caps, versions and parameters mean, in the browser and the CLI.

](https://www.jsonify.com/docs/runs/running)[**Run detail**

The same steps, activity and logs the CLI returns, on a page.

](https://www.jsonify.com/docs/runs/run-detail)[**Query and export**

The SQL the query command accepts.

](https://www.jsonify.com/docs/datasets/query-and-export)[**Connect your agent (MCP)**

Prefer a chat assistant to a terminal? Same access, no key.

](https://www.jsonify.com/docs/integrations/mcp)

[PreviousConnect your agent (MCP)](https://www.jsonify.com/docs/integrations/mcp) [NextWorkspace settings](https://www.jsonify.com/docs/workspace/settings)

Something missing or wrong? [Tell us](https://www.jsonify.com/contact).[Build it →](https://factory.jsonify.com/setup)

## On this page