Shortcut

https://shortcut.ai/docs
Admin
Shortcut is an AI agent for spreadsheets that automates Excel and .xlsx work across a CLI and...
Tokens:13,662
Snippets:155
Trust Score:8.1
Update:8 hours ago
Show doc for...
Tokens:
Raw
### Install and sign in to Shortcut CLI

Source: https://shortcut.ai/docs/agent-integration

Install the `shortcutxl` package globally (requires Node.js 22.12+) and sign in once per user. The sign-in is stored and refreshed on the machine, so later calls run with that user's permissions.

```bash
# Install once (Node.js 22.12+)
npm install -g shortcutxl

# Each user signs in once
shortcut login
```

--------------------------------

### Install and launch Shortcut CLI

Source: https://shortcut.ai/docs/cli

Install the shortcutxl package globally, then launch the terminal interface, desktop app, or run a Platform API cloud job. Requires Node.js 22.12 or later.

```bash
# Install once
npm install -g shortcutxl

# Launch the terminal interface
shortcut

# Or launch the desktop app
shortcut app

# Or run a Platform API cloud job from your terminal
shortcut api run "Combine these sheets into a report" --input data.xlsx
```

--------------------------------

### Install Shortcut plugin for Claude Code and Codex

Source: https://shortcut.ai/docs/cli

Install the Shortcut plugin for Claude Code and the skill for Codex, then use the shortcut command from your coding agent. The plugin marketplace and skill installer commands are shown.

```bash
# Claude Code: install the plugin once
/plugin marketplace add fundamental-research-labs/shortcutxl-plugins
/plugin install shortcutxl@shortcut

# Codex: install the skill, then restart Codex
$skill-installer install https://github.com/fundamental-research-labs/shortcutxl-plugins/tree/master/shortcutxl

# Your coding agent then calls shortcut itself
shortcut -p "Create a DCF model for AAPL"
shortcut --session a1b2c3d4 -p "Now add a sensitivity table"
```

--------------------------------

### Python: Run a spreadsheet job and download results

Source: https://shortcut.ai/docs/platform-api

Authenticates with the Shortcut AI API using an API key, finds the 'powerpoint_creation' skill, submits a job with a prompt, polls for completion, and downloads the resulting workbook and any artifacts.

```python
import os
import time

import requests

API_KEY = os.environ["SHORTCUT_API_KEY"]
BASE_URL = "https://api.shortcut.ai/api/spreadsheets"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def wait_for_run(run_id):
    while True:
        response = requests.get(f"{BASE_URL}/{run_id}", headers=HEADERS, timeout=30)
        response.raise_for_status()
        run = response.json()
        print(f"Status: {run['status']}")

        if run["status"] == "completed":
            return run
        if run["status"] in {"failed", "cancelled"}:
            raise RuntimeError(run.get("error", f"Run {run['status']}"))

        time.sleep(3)


# Always use the source-qualified id returned by the skills endpoint.
response = requests.get(f"{BASE_URL}/skills", headers=HEADERS, timeout=30)
response.raise_for_status()
skill = next((
    item
    for item in response.json()["skills"]
    if item["folderName"] == "powerpoint_creation"
), None)
if skill is None:
    raise RuntimeError("The powerpoint_creation skill is not available for this account")

response = requests.post(
    BASE_URL,
    headers=HEADERS,
    json={
        "prompt": "Create a Q1 sales workbook and a presentation summarizing it",
        "mode": "action",
        "skills": [skill["id"]],
    },
    timeout=30,
)
response.raise_for_status()
run_id = response.json()["runId"]
run = wait_for_run(run_id)

if run.get("downloadUrl"):
    response = requests.get(f"{BASE_URL}/{run_id}/download", headers=HEADERS, timeout=120)
    response.raise_for_status()
    with open("result.xlsx", "wb") as output:
        output.write(response.content)

for filename in run.get("artifacts", []):
    response = requests.get(
        f"{BASE_URL}/{run_id}/artifacts/{filename}",
        headers=HEADERS,
        timeout=120,
    )
    response.raise_for_status()
    with open(filename, "wb") as output:
        output.write(response.content)
    print(f"Saved {filename}")
```

--------------------------------

### shortcut api --help command list

Source: https://shortcut.ai/docs/platform-api

The full list of `shortcut api` commands as printed by `shortcut api --help`. Each command shows its usage and a brief description of what it does.

```bash
shortcut api run <prompt> [options]     # upload, submit, wait, and download in one command
shortcut api upload <file...>           # upload files, returns a file id
shortcut api submit <prompt> [options]  # submit a task, returns a run id
shortcut api status <run-id>            # check on a run
shortcut api wait <run-id>              # wait until a run finishes
shortcut api download <run-id> [-o f]   # download the result workbook
shortcut api artifacts <run-id>         # list extra output files
shortcut api artifact <run-id> <name>   # download one extra output file
shortcut api cancel <run-id>            # cancel a run
shortcut api runs                       # list recent runs
shortcut api skills                     # list the skills the user can use
shortcut api verify                     # check the connection
```

--------------------------------

### Run tasks in the user's Excel with shortcut -p

Source: https://shortcut.ai/docs/agent-integration

Use `shortcut -p` to run tasks on the user's machine in desktop Excel (Windows with desktop Office). The `--mode json` option outputs one event per line. `--skip-office-permissions` allows the run to proceed without keyboard approval. Use `--session` to continue the same piece of work across calls. `--agent-mode ask` performs read-only analysis.

```bash
# --skip-office-permissions lets the run proceed with no one at the
# keyboard to approve; see Approvals below before enabling more.
shortcut --skip-office-permissions -p \
  "Refresh the model and update the summary tab" --mode json

# Continue the same piece of work across calls
# (every run prints a session id to reuse)
shortcut --skip-office-permissions --session a1b2c3d4 -p \
  "Now add a sensitivity table" --mode json

# Read-only analysis instead of editing
shortcut --agent-mode ask -p "Audit this model for errors" --mode json
```

--------------------------------

### Shortcut CLI: Login, run, and manage spreadsheet jobs

Source: https://shortcut.ai/docs/platform-api

Shows the Shortcut CLI commands for authenticating, submitting a job, uploading files, checking status, waiting, and downloading results. Also demonstrates using an API key for webhook-based submissions.

```bash
# Sign in once; your OAuth session authenticates every call
shortcut login

# Submit a job, wait for it, and download the result in one command
shortcut api run "Combine these regional sheets and add a summary pivot" \
  --input q3-sales.xlsx \
  --output q3-report.xlsx

# Or drive each step yourself
shortcut api upload q3-sales.xlsx
shortcut api submit "Combine these regional sheets and add a summary pivot" \
  --init-file-id <file-id> --mode action
shortcut api status <run-id>
shortcut api wait <run-id>
shortcut api download <run-id> -o q3-report.xlsx

# Webhooks need an API key
shortcut api submit "..." --auth api-key --webhook-url https://example.com/shortcut
```

--------------------------------

### Run tasks in Shortcut's cloud with shortcut api

Source: https://shortcut.ai/docs/agent-integration

Use `shortcut api run` to send a task to the Platform API, which uploads files, waits for completion, and downloads the result. Use `--json` for machine-readable output. List available skills and runs with `shortcut api skills` and `shortcut api runs`.

```bash
shortcut api run "Combine these regional sheets and add a summary pivot" \
  --input q3-sales.xlsx \
  --output q3-report.xlsx \
  --json

# List what the signed-in user can use
shortcut api skills
shortcut api runs
```

--------------------------------

### Analyze a file with the Shortcut AI API (Python)

Source: https://shortcut.ai/docs/platform-api

Uploads data.xlsx, then submits a prompt in 'ask' mode to analyze the workbook and summarize key trends. Polls for completion and prints the summary. Requires the SHORTCUT_API_KEY environment variable.

```Python
import os
import time

import requests

API_KEY = os.environ["SHORTCUT_API_KEY"]
BASE_URL = "https://api.shortcut.ai/api/spreadsheets"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def wait_for_run(run_id):
    while True:
        response = requests.get(f"{BASE_URL}/{run_id}", headers=HEADERS, timeout=30)
        response.raise_for_status()
        run = response.json()
        print(f"Status: {run['status']}")

        if run["status"] == "completed":
            return run
        if run["status"] in {"failed", "cancelled"}:
            raise RuntimeError(run.get("error", f"Run {run['status']}"))

        time.sleep(3)


with open("data.xlsx", "rb") as workbook:
    response = requests.post(
        f"{BASE_URL}/upload",
        headers=HEADERS,
        files={"file": workbook},
        timeout=120,
    )
response.raise_for_status()
file_id = response.json()["fileId"]

response = requests.post(
    BASE_URL,
    headers=HEADERS,
    json={
        "prompt": "Analyze this workbook and summarize the key trends",
        "initFile": file_id,
        "mode": "ask",
    },
    timeout=30,
)
response.raise_for_status()
run_id = response.json()["runId"]

run = wait_for_run(run_id)
print(run.get("summary", "No summary was produced."))
```

--------------------------------

### Submit a spreadsheet run with an attached file (Python)

Source: https://shortcut.ai/docs/platform-api

Uploads data.xlsx to the API, then submits a prompt in 'action' mode using the uploaded file as initFile. Polls for completion and downloads the result as result.xlsx. Requires the SHORTCUT_API_KEY environment variable.

```Python
import os
import time

import requests

API_KEY = os.environ["SHORTCUT_API_KEY"]
BASE_URL = "https://api.shortcut.ai/api/spreadsheets"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def wait_for_run(run_id):
    while True:
        response = requests.get(f"{BASE_URL}/{run_id}", headers=HEADERS, timeout=30)
        response.raise_for_status()
        run = response.json()
        print(f"Status: {run['status']}")

        if run["status"] == "completed":
            return run
        if run["status"] in {"failed", "cancelled"}:
            raise RuntimeError(run.get("error", f"Run {run['status']}"))

        time.sleep(3)


with open("data.xlsx", "rb") as workbook:
    response = requests.post(
        f"{BASE_URL}/upload",
        headers=HEADERS,
        files={"file": workbook},
        timeout=120,
    )
response.raise_for_status()
file_id = response.json()["fileId"]

response = requests.post(
    BASE_URL,
    headers=HEADERS,
    json={
        "prompt": "Create a pivot table summarizing sales by region",
        "initFile": file_id,
        "mode": "action",
    },
    timeout=30,
)
response.raise_for_status()
run_id = response.json()["runId"]

run = wait_for_run(run_id)
if run.get("downloadUrl"):
    result = requests.get(f"{BASE_URL}/{run_id}/download", headers=HEADERS, timeout=120)
    result.raise_for_status()
    with open("result.xlsx", "wb") as output:
        output.write(result.content)
else:
    print(run.get("summary", "Run completed without a workbook."))
```

--------------------------------

### Submit a basic spreadsheet run and download result (Python)

Source: https://shortcut.ai/docs/platform-api

Submits a prompt to the Shortcut AI Spreadsheets API in 'action' mode, polls for completion, and downloads the resulting workbook as result.xlsx. Requires the SHORTCUT_API_KEY environment variable. Raises RuntimeError if the run fails or is cancelled.

```Python
import os
import time

import requests

API_KEY = os.environ["SHORTCUT_API_KEY"]
BASE_URL = "https://api.shortcut.ai/api/spreadsheets"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def wait_for_run(run_id):
    while True:
        response = requests.get(f"{BASE_URL}/{run_id}", headers=HEADERS, timeout=30)
        response.raise_for_status()
        run = response.json()
        print(f"Status: {run['status']}")

        if run["status"] == "completed":
            return run
        if run["status"] in {"failed", "cancelled"}:
            raise RuntimeError(run.get("error", f"Run {run['status']}"))

        time.sleep(3)


response = requests.post(
    BASE_URL,
    headers=HEADERS,
    json={
        "prompt": "Create a sales report with summary statistics",
        "mode": "action",
    },
    timeout=30,
)
response.raise_for_status()
run_id = response.json()["runId"]
print(f"Run submitted: {run_id}")

run = wait_for_run(run_id)
if run.get("downloadUrl"):
    result = requests.get(f"{BASE_URL}/{run_id}/download", headers=HEADERS, timeout=120)
    result.raise_for_status()
    with open("result.xlsx", "wb") as output:
        output.write(result.content)
    print("Saved result.xlsx")
else:
    print(run.get("summary", "Run completed without a workbook."))
```

--------------------------------

### Submit a spreadsheet run with a skill (Python)

Source: https://shortcut.ai/docs/platform-api

Submits a prompt to the Shortcut AI Spreadsheets API with a 'skill' parameter. The code is incomplete in the source, showing only the beginning of the request. Requires the SHORTCUT_API_KEY environment variable.

```Python
import os
import time

import requests

API_KEY = os.environ["SHORTCUT_API_KEY"]
BASE_URL = "https://api.shortcut.ai/api/spreadsheets"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def wait_for_run(run_id):
    while True:
        response = requests.get(f"{BASE_URL}/{run_id}", headers=HEADERS, timeout=30)
        response.raise_for_status()
        run = response.json()
        print(f"Status: {run['status']}")

        if run["status"] == "completed":
            return run
        if run["status"] in {"failed", "cancelled"}:
            raise RuntimeError(run.get("error", f"Run {run['status']}"))

        time.sleep(3)


response = requests.post(
    BASE_URL,
    headers=HEADERS,
    json={
        "prompt": "Create a sales report with summary statistics",
        "mode": "action",
        "skill": "..."
    },
    timeout=30,
)
response.raise_for_status()
run_id = response.json()["runId"]
print(f"Run submitted: {run_id}")

run = wait_for_run(run_id)
if run.get("downloadUrl"):
    result = requests.get(f"{BASE_URL}/{run_id}/download", headers=HEADERS, timeout=120)
    result.raise_for_status()
    with open("result.xlsx", "wb") as output:
        output.write(result.content)
    print("Saved result.xlsx")
else:
    print(run.get("summary", "Run completed without a workbook."))
```
Tokens:
Raw