Documentation sections

CLI + local skills

Build and deploy a workflow

Workflows are scheduled or triggered jobs that run on SolidActions servers even when Claude is offline. This path uses Node.js, a terminal, the SolidActions CLI, and local agent skills.

Last reviewed July 14, 2026 · @solidactions/cli 1.31.1

Connecting hosted MCP is not required for this quickstart.

The CLI authenticates with an API key. The hosted MCP connection authenticates in a browser with OAuth. You can use either path independently or connect Claude as well.

What you need

  • A SolidActions account and workspace.
  • Node.js 24 and npm. Confirm with node --version and npm --version.
  • Claude Code for this quickstart, or a local agent that reads AGENTS.md and .agents/skills/.
  • A terminal on macOS, Linux, or Windows through a shell that can run Node.js and npm.

1. Install the CLI

npm install -g @solidactions/cli
solidactions --version

2. Create an API key and authenticate

  1. Sign in at https://app.solidactions.com.
  2. Open your workspace, then go to Settings → API Keys.
  3. Create a key for CLI use and copy it. Treat it like a password.
  4. Run the command below. Paste the key only when the masked prompt asks for SolidActions API key.
solidactions login --global

The prompt does not echo the key. Do not add the key to the command itself: a positional value can be saved in shell history and exposed in the process list. Confirm the selected workspace without printing the key:

solidactions whoami

Use the masked login flow.

The masked no-argument login flow is available in CLI 1.31.1. If your installed CLI still requires a key as a positional argument, do not paste a real key there; update the CLI first.

3. Scaffold the project and install dependencies

Run this from a directory where a new my-first-job folder can be created:

solidactions init my-first-job --claude
cd my-first-job
npm install
npm run build

For a local agent that uses the shared AGENTS.md convention, replace the first line withsolidactions init my-first-job --agents. This selects a local instruction-file layout; it does not establish hosted-MCP support for that agent.

The generated project includes:

  • solidactions.yaml with a dependency-free workflow named hello.
  • src/hello.ts, package.json, and a lockfile.
  • CLAUDE.md for --claude, or AGENTS.md for --agents.
  • .solidactions/sdk-reference.md with the SDK reference.
  • Five local skill files under .claude/skills/ or .agents/skills/.
ls .claude/skills/solidactions-*.md
test -f .solidactions/sdk-reference.md
test -f CLAUDE.md

These verification commands use a POSIX-compatible shell. With --agents, substitute.agents/skills/ and AGENTS.md. PowerShell users can inspect the same paths withGet-ChildItem and Test-Path.

The five installed skills are:

  • solidactions-getting-started
  • solidactions-workflow-coding
  • solidactions-deploy-and-config
  • solidactions-oauth-actions
  • solidactions-crew-skills

4. Restart your agent and verify skill discovery

Close the current agent session, start a new one in my-first-job, and use this prompt. A restart is required so the agent discovers the newly installed project instructions and skills.

Use the SolidActions getting-started skill to inspect this project. Tell me the workflow id in solidactions.yaml and the next safe setup step. Do not deploy or change files.

A passing result identifies the hello workflow and explains a SolidActions-specific next step from the installed guidance. Merely seeing files in the skills directory does not prove the restarted agent can discover and apply them.

5. Deploy the generated workflow

From the project directory, run:

solidactions project deploy my-first-job -e production

The deploy should identify the my-first-job production project and the hello workflow. Stop and read the full error if authentication, entitlement, workspace, or validation fails.

6. Start a run and inspect the result

solidactions run start my-first-job hello -e production -i '{"name":"Ada"}' --wait

The CLI prints a numeric run ID and waits for a completed or failed state. Use that numeric ID to inspect the run:

solidactions run view RUN_ID

The generated workflow is designed to return a greeting for Ada plus a processed timestamp. You can also open the project and its run history in the SolidActions app.

Production smoke test still required before broad promotion.

The command syntax, scaffold contents, and generated workflow are source/test verified. A clean account must still pass the published-package deploy and run sequence without private instructions before this guide is treated as launch evidence.

Use an existing project

solidactions init requires an empty target. To install or refresh the helper file, SDK reference, and skills in an existing project, run the matching command from its root, then restart the agent:

solidactions ai init --claude
# or
solidactions ai init --agents

If something fails, use Troubleshooting. For package and API links, see Reference.