Command line

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

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.

Read or Operator

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.

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

Command reference

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

Workspace

Pipelines

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

Runs

Datasets

Deliverables

Jason

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

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

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

What’s next