gigstack CLI

gigstack automates invoicing and revenue management for Mexican businesses. This CLI lets you create CFDI invoices, manage payments, clients, and receipts directly from your terminal or CI/CD pipeline.

Built on the gigstack API.

What's new in 0.3.0

Descarga Masiva SAT — full read + hire surface from the terminal: gigstack invoices sat status | activate | list | get | retry | pdf. List your team's downloaded SAT mirror (received from suppliers) AND your own issued CFDIs, retry stuck XML downloads, generate PDFs, hire/cancel the service. See the Descarga Masiva SAT section.
Paginated JSON envelopes (breaking) — every list command in --json mode now returns { data, has_more, next, total } instead of a bare array. Pipe next back as --next <token> to paginate. Migration: read .data on existing scripts.
Agent-friendly fixes — --json no longer leaks the spinner into stdout when piped; gigstack invoices complements works (was 405); gigstack receipts list --client <id> works (Firestore composite index now exists).
Agent context — gigstack context descarga_masiva_sat ships a full domain-knowledge topic for AI agents (concepts, statuses, actions, pricing, tips). gigstack context --all --json for one-shot bulk-load.

Installation

npm install -g gigstack

After installing, the gigstack command is available globally.

Development setup

git clone https://github.com/disruptive-learning/gigstack-cli.git
cd gigstack-cli
npm install
npm run build
npm link

Quick start

# Authenticate with your API key (get it at app.gigstack.pro/settings > API)
gigstack login

# Verify your account and connection
gigstack whoami
gigstack doctor

# See a financial summary of your team
gigstack status

Authentication

The CLI resolves credentials in this order:

Environment variable GIGSTACK_API_KEY
Active profile saved in ~/.config/gigstack/credentials.json

Credentials are stored with 0600 permissions (owner-only read/write).

Commands

gigstack login                        # Interactive login
gigstack login -k <api-key>          # Login with key inline
gigstack login -k <key> -p prod      # Save as named profile
gigstack logout                       # Remove credentials
gigstack whoami                       # Show current account
gigstack profiles                     # List saved profiles
gigstack switch <profile>             # Switch active profile

Multiple profiles

gigstack login -k <key-production> -p production
gigstack login -k <key-staging> -p staging
gigstack switch production
gigstack profiles

For AI agents

The context command provides structured domain knowledge that helps agents understand gigstack concepts, statuses, relationships, and available actions.

Topics

Topic	What it covers
`payments`	Payment lifecycle, statuses, automation types, payment forms
`invoices`	CFDI types (I/E/P/T), PUE vs PPD, folios, cancellation motives
`receipts`	Sales receipts, self-invoice portal, global invoicing (EOM)
`clients`	Fiscal data (RFC, tax system), validation, auto-creation
`cobranza`	Collections/accounts receivable, PPD aging, partial payments
`automations`	Event-driven actions triggered by payments
`services`	Product/service catalog, SAT keys
`webhooks`	Real-time event notifications

Usage

gigstack context                       # List all topics
gigstack context payments              # Full knowledge on payments
gigstack context payments --short      # Summary only
gigstack context payments --json       # Machine-readable output

JSON mode for agents

Every command supports --json for structured output that agents can parse:

gigstack status --json
gigstack clients list --json
gigstack invoices list --json --from 2026-01 --to 2026-03

List endpoints return paginated envelopes

In --json mode, every list command returns:

{ "data": [...], "has_more": false, "next": null, "total": 599 }

Pipe next back as --next <token> for the following page. total is the unfiltered server-side count when the API provides it (otherwise null).

Breaking change in 0.3.0: previous versions returned a bare array. To keep existing scripts working, migrate to reading .data from the response.

Commands reference

Status and diagnostics

gigstack status                        # Financial dashboard
gigstack status --from 2026-01         # Filter by date range
gigstack status --from 30d --to today  # Last 30 days
gigstack doctor                        # Full system diagnostics

The status command shows:

Invoices: valid/cancelled, PUE/PPD breakdown with totals
Payments: succeeded/pending/failed with amounts
Receipts: pending self-invoicing vs invoiced
Cobranza: PPD invoices with outstanding balance, aging buckets (0-15, 16-30, 31-60, 61-90, 90+ days)
Conciliation: invoiced vs collected amounts and the difference

Quick pay

Register a payment, auto-create the client if needed, and send the self-invoice portal.

gigstack pay                           # Interactive mode

gigstack pay \
  --email client@company.com \
  --name "Juan Perez" \
  --description "Professional services" \
  --amount 5000 \
  --iva \
  --payment-form 03

# From stdin (for agents)
echo '{"email":"client@co.com","description":"Consulting","amount":5000}' | gigstack pay --stdin --json

Automation options (--automation):

Value	Description
`pue_invoice`	PUE invoice stamped immediately (default)
`ppd_invoice_and_complement`	PPD invoice + payment complement
`none`	Record payment only, no invoice

Clients

gigstack clients list                  # List clients
gigstack clients get <id>              # View details
gigstack clients create                # Create (interactive)
gigstack clients update <id>           # Update (interactive or flags)
gigstack clients search "ACME"         # Search by name, RFC, or email
gigstack clients validate <id>         # Validate fiscal data against SAT
gigstack clients portal                # Generate customer portal link (interactive)
gigstack clients portal --email cli@co.com  # By email
gigstack clients portal --id client_abc     # By client ID
gigstack clients delete <id>           # Delete

# Create with flags
gigstack clients create \
  --name "Mi Empresa SA de CV" \
  --rfc MEMP850101AAA \
  --email billing@company.com \
  --tax-system 601 \
  --zip 06600

Invoices

gigstack invoices list                 # List income invoices
gigstack invoices get <uuid>           # View details
gigstack invoices create               # Create (interactive or flags)
gigstack invoices cancel <uuid> --motive 02  # Cancel with SAT
gigstack invoices search "ACME"        # Search by client name, RFC, or UUID
gigstack invoices files <uuid>         # Get PDF/XML download URLs
gigstack invoices download <uuid>      # Download PDF/XML to disk
gigstack invoices send <uuid>          # Send invoice by email
gigstack invoices drafts list          # List draft pre-invoices
gigstack invoices drafts stamp <uuid>  # Stamp a draft into a real CFDI
gigstack invoices credit-notes         # List credit notes (egress invoices)
gigstack invoices complements          # List payment complements
gigstack invoices complements --invoice <uuid>  # Filter by parent PPD invoice
gigstack invoices sat list             # List CFDIs received from SAT (Descarga Masiva)
gigstack invoices sat get <uuid>       # View a SAT-downloaded invoice
gigstack invoices sat status           # Check Descarga Masiva activation status

# Create with flags
gigstack invoices create \
  --client client_abc123 \
  --items '[{"description":"Consulting","quantity":1,"unit_price":5000,"product_key":"84111506","unit_key":"E48","taxes":[{"type":"IVA","rate":0.16,"factor":"Tasa","withholding":false}]}]' \
  --payment-form 03 \
  --payment-method PUE

Cancellation motives: 01 = replacement, 02 = no commercial activity, 03 = wrong operation, 04 = related to global invoice.

Payments

gigstack payments list                 # List payments
gigstack payments get <id>             # View details
gigstack payments request              # Create a payment link
gigstack payments register             # Record a payment already received
gigstack payments refund <id>          # Refund a payment

# Request payment (generates a payment link)
gigstack payments request \
  --client client_abc123 \
  --items '[{"description":"Service","quantity":1,"unit_price":3000}]' \
  --methods card,bank,oxxo \
  --send-email

# Register payment received
gigstack payments register \
  --client client_abc123 \
  --items '[{"description":"Service","quantity":1,"unit_price":3000}]' \
  --payment-form 03

Services

gigstack services list                 # List product/service catalog
gigstack services get <id>             # View details
gigstack services create               # Create a service
gigstack services update <id>          # Update (interactive or flags)
gigstack services delete <id>          # Delete

# Create with flags
gigstack services create \
  --description "Monthly consulting" \
  --price 10000 \
  --product-key 84111506 \
  --unit-key E48 \
  --iva

Receipts

gigstack receipts list                 # List sales receipts
gigstack receipts stamp <id>           # Stamp a receipt (generate invoice)
gigstack receipts cancel <id>          # Cancel a receipt

Webhooks

gigstack webhooks list                 # List configured webhooks
gigstack webhooks create \
  --url https://example.com/webhook \
  --events invoice.created,payment.succeeded
gigstack webhooks delete <id>          # Delete a webhook

Teams

gigstack teams list                    # List teams
gigstack teams get <id>                # View team details
gigstack teams integrations            # View active integrations

Descarga Masiva SAT

Automated download of every CFDI the SAT has issued to or for your RFC, including invoices issued by your suppliers. Useful for compliance, expense tracking, and reconciling what your vendors actually billed you.

Setup prerequisites: Initial FIEL upload (.cer + .key files) and RFC registration are sensitive operations and only run from the web UI: app.gigstack.pro/gastos. Once your FIEL is uploaded, the rest of the lifecycle (activate, list, retry, PDF) is available from the CLI.

Pricing:

$0.20 MXN per XML downloaded (metered)
$400 MXN/mes per RFC add-on (only for plans that don't already include the feature)

Hire the service

gigstack invoices sat status            # See activation state and next step
gigstack invoices sat activate          # Confirms pricing, then enables on your subscription
gigstack invoices sat deactivate        # Cancel (stops new downloads)

status returns one of:

Status	Meaning
`active`	Already enabled; downloads are billing
`needs_activation`	Plan includes the feature — run `activate` (no monthly add-on cost)
`needs_addon`	Plan doesn't include it — `activate` adds the $400/RFC/month add-on
`needs_upgrade`	Free plan — upgrade required at app.gigstack.pro/billing

Daily usage

gigstack invoices sat list                              # Recent downloads
gigstack invoices sat list --direction received         # Only invoices issued to you (suppliers)
gigstack invoices sat list --direction issued           # Only invoices you issued
gigstack invoices sat list --type I --status Vigente    # Filter by CFDI type and status
gigstack invoices sat list --from 2026-01 --to 2026-03  # Date range
gigstack invoices sat list --issuer-rfc XAXX010101000   # Filter by issuer RFC
gigstack invoices sat get <uuid>                        # Full detail
gigstack invoices sat retry <uuid>                      # Retry stuck/errored XML download
gigstack invoices sat pdf <uuid>                        # Generate and save PDF
gigstack invoices sat pdf <uuid> --out ./invoices       # Custom output dir
gigstack invoices sat download <uuid>                   # Convenience: PDF only (XML is web-only)

The XML for SAT-downloaded CFDIs is not exposed via the API; it can only be downloaded from the web UI at app.gigstack.pro/gastos. The CLI's pdf and download commands generate the PDF on demand from the cached XML.

Scheduled downloads

gigstack invoices sat schedule show                                # Current schedule + sync status
gigstack invoices sat schedule history                             # Last 20 scheduled runs
gigstack invoices sat schedule set --time 21:00 --types received --days-back 7
gigstack invoices sat schedule set --enabled false --time 21:00 --types received --days-back 7

set requires the team to already have FIEL uploaded and the RFC registered with the SAT (both done from the web UI).

Export

Export data to CSV (default) or JSON with automatic pagination. Output goes to stdout so you can pipe or redirect it.

gigstack export invoices               # Export all invoices as CSV
gigstack export payments --format json # Export payments as JSON
gigstack export receipts --from 2026-01 --to 2026-03
gigstack export clients > clients.csv

# With filters
gigstack export invoices --status valid --from 2026-01
gigstack export payments --status succeeded --currency MXN

Supported entities: invoices, payments, receipts, clients.

Forecast

Project revenue, collections risk, EOM receipts, and cash flow based on historical data.

gigstack forecast                      # This month projection (3 months ahead)
gigstack forecast --months 6           # Project 6 months ahead
gigstack forecast --json               # Structured output for agents

Shows:

Revenue trend (avg monthly, growth %, projection)
Cobranza risk (PPD aging probability, expected recovery vs likely loss)
EOM global invoice estimate (pending receipts x historical self-invoice rate)
Cash flow projection (pending links x conversion rate + expected PPD collections)

Shell completions

# Bash — add to ~/.bashrc
eval "$(gigstack completions bash)"

# Zsh — add to ~/.zshrc
eval "$(gigstack completions zsh)"

# Fish — save to completions directory
gigstack completions fish > ~/.config/fish/completions/gigstack.fish

Filtering and pagination

All list commands share these options:

Flag	Description	Default
`-l, --limit <n>`	Results per page (1-100)	`20`
`--next <token>`	Pagination cursor from previous response	—
`--from <date>`	Start date	—
`--to <date>`	End date	—
`--sort <dir>`	Sort direction: `asc` or `desc`	`desc`
`--order-by <field>`	Sort field: `timestamp` or `name`	`timestamp`

Date formats accepted: YYYY-MM-DD, YYYY-MM (expands to full month), 30d / 7d (relative days), today.

gigstack invoices list --from 2026-01 --to 2026-03
gigstack payments list --from 30d --limit 50
gigstack receipts list --sort asc --limit 100

When there are more results, the CLI prints a --next token. Pass it to get the next page:

gigstack invoices list --limit 20
# ... shows --next abc123
gigstack invoices list --limit 20 --next abc123

Global options

Flag	Description
`--json`	JSON output (for scripts and agents)
`--team <id>`	Operate on a specific team (gigstack Connect)
`-h, --help`	Show help
`-V, --version`	Show version

Examples

Check collections (cobranza)

# Quick summary with aging breakdown
gigstack status

# JSON output for processing
gigstack status --json | jq '.cobranza'

# List PPD invoices with outstanding balance
gigstack invoices list --json | jq '[.[] | select(.payment_method == "PPD" and .last_balance > 0)]'

Create and send an invoice

# Interactive — walks you through client search, items, and payment method
gigstack invoices create

# Scripted — everything via flags
gigstack invoices create \
  --client client_abc123 \
  --items '[{"description":"Web development","quantity":40,"unit_price":500,"product_key":"84111506","unit_key":"HUR","taxes":[{"type":"IVA","rate":0.16,"factor":"Tasa","withholding":false}]}]' \
  --payment-form 03 \
  --payment-method PUE \
  --send-email

Export a monthly report

# Invoices for March 2026
gigstack export invoices --from 2026-03 --to 2026-03 > invoices-march.csv

# All succeeded payments this year as JSON
gigstack export payments --from 2026-01 --status succeeded --format json > payments-2026.json

# Client directory
gigstack export clients > clients.csv

Charge and invoice in one step

gigstack pay \
  --email client@company.com \
  --name "Client Name" \
  --description "March consulting" \
  --amount 15000 \
  --iva \
  --payment-form 03

Use in CI/CD

export GIGSTACK_API_KEY=your_api_key
gigstack invoices list --json | jq '.[] | {uuid, total, status}'
gigstack status --json

Agent workflow

# 1. Understand the domain
gigstack context payments --json

# 2. Get current financial state
gigstack status --json

# 3. Find a client
gigstack clients search "ACME" --json

# 4. Create an invoice
gigstack invoices create --client client_abc --items '[...]' --payment-form 03 --json

Development

git clone https://github.com/disruptive-learning/gigstack-cli.git
cd gigstack-cli
npm install
npm run dev -- --help       # Run in development mode
npm run build               # Compile to dist/

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build.mjs		build.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

gigstack CLI

What's new in 0.3.0

Installation

Development setup

Quick start

Authentication

Commands

Multiple profiles

For AI agents

Topics

Usage

JSON mode for agents

List endpoints return paginated envelopes

Commands reference

Status and diagnostics

Quick pay

Clients

Invoices

Payments

Services

Receipts

Webhooks

Teams

Descarga Masiva SAT

Hire the service

Daily usage

Scheduled downloads

Export

Forecast

Shell completions

Filtering and pagination

Global options

Examples

Check collections (cobranza)

Create and send an invoice

Export a monthly report

Charge and invoice in one step

Use in CI/CD

Agent workflow

Development

Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages