Welcome to Okinawa

This guide will walk you through setting up Okinawa and creating your first automation workflow in under 5 minutes. Whether you're a developer looking to automate CI/CD pipelines, a marketer setting up lead nurturing flows, or an operations manager streamlining internal processes, Okinawa gives you the building blocks to go from idea to production in minutes — not weeks.

By the end of this guide, you'll have a working workflow deployed to the cloud, processing real events from your connected tools.

Prerequisites

Before you begin, make sure you have the following:

• A Okinawa account — Sign up at okinawa.com. The free tier includes 1,000 workflow executions per month, which is more than enough to get started.
• Node.js 18+ — Required for the CLI. We recommend using nvm or fnm to manage Node versions.
• A tool or service to connect — Slack, GitHub, Salesforce, or any of our 200+ supported integrations.
• Basic YAML knowledge — Workflows are defined in YAML. If you've written a Docker Compose file or GitHub Actions workflow, you'll feel right at home.

Step 1: Install the CLI

The Okinawa CLI is your primary tool for creating, testing, and deploying workflows from the terminal. Install it globally using npm:

npm install -g @okinawa/cli

Verify the installation:

okinawa --version\n# Output: 3.2.1

Then authenticate with your account. This opens a browser window where you can log in and authorize the CLI:

okinawa auth login

You'll see a success message confirming your account is linked. The CLI stores your credentials securely in your system's keychain.

Step 2: Create your first workflow

Initialize a new workflow project. This creates a directory with a pre-configured template:

okinawa init my-first-workflow\ncd my-first-workflow

The generated project structure looks like this:

my-first-workflow/\n├── workflow.yaml # Main workflow definition\n├── config.yaml # Environment and secrets\n├── README.md # Auto-generated docs\n└── .okinawa/ # Internal cache\n └── state.json

Open workflow.yaml in your editor. You'll see a basic template with placeholders ready to customize.

Step 3: Configure a trigger

Triggers define when your workflow runs. For this tutorial, we'll use a webhook trigger — this means your workflow runs whenever it receives an HTTP request:

triggers:\n - type: webhook\n path: /my-trigger\n method: POST\n headers:\n x-api-key: "{{secrets.WEBHOOK_API_KEY}}"

The path is appended to your unique workflow URL. The optional headers block lets you require an API key for security.

Step 4: Add action steps

Steps are the actions your workflow performs when triggered. Let's add two steps: one to log the incoming data and another to send a Slack notification:

steps:\n - name: Log Event\n type: builtin\n action: log\n message: "Received event: {{trigger.body.event_type}}"\n\n - name: Send Notification\n type: slack\n action: sendMessage\n channel: "#notifications"\n message: |\n New event received!\n Type: {{trigger.body.event_type}}\n Data: {{trigger.body.data | json}}

Notice the {{trigger.body}} syntax — this references the incoming webhook payload. You can use dot notation to access nested fields and pipe them through filters like json, date, or uppercase.

Step 5: Test locally

Before deploying, test your workflow locally. The CLI includes a built-in test runner that simulates trigger events:

okinawa test --trigger webhook --body '{"event_type": "test", "data": {"message": "Hello!"}}'

You'll see the output of each step in your terminal. If everything works, you'll see the log message and a preview of the Slack notification.

Step 6: Deploy to production

When you're satisfied with your workflow, deploy it to the cloud with a single command:

okinawa deploy\n\n# Output:\n✓ Workflow deployed successfully\n✓ Webhook URL: https://hooks.okinawa.com/wf_abc123/my-trigger\n✓ Active triggers: 1\n✓ Version: 1.0.0

Your workflow is now live. Any POST request to the webhook URL will trigger execution. You can monitor runs from the dashboard at app.okinawa.com/dashboard.

Next steps

Congratulations! You've created and deployed your first Okinawa workflow. Here's where to go from here:

• Building Complex Workflows — Add conditions, loops, and error handling
• Connecting Your First Integration — Link tools like Slack, GitHub, and Salesforce
• Working with Agents — Create autonomous AI-powered workers
• API Authentication — Integrate Okinawa into your own application