Skip to content

cli.md

Latest commit

 

History

History
148 lines (104 loc) · 4.67 KB

cli.md

File metadata and controls

148 lines (104 loc) · 4.67 KB
Raw

uraijs CLI reference

The uraijs CLI is for local development and CI of Urai tools, workflows, and libraries. It never talks to the Urai server — you deploy by git push to your Urai remote. Code runs in the UraiJS runtime (a sandboxed JavaScript/ TypeScript runtime, not Node.js).

Output contract (CI-friendly)

  • stdout = the machine-consumable payload only (result JSON, tool list, …).
  • stderr = human "chrome": status, headers, errors.
  • Every command returns a meaningful exit code (non-zero on failure).
  • Global flags: --json (machine-readable payload, chrome suppressed), --quiet (drop chrome, keep payload). Colors auto-disable when not a TTY, or under NO_COLOR / CI.
uraijs call tool.ts greet -a '{"name":"Ada"}' --json | jq .

Scaffolding

uraijs init [name] --type tool|workflow|library

Create a new project: entry script, urai.toml, .gitignore, git init, editor support (urai.d.ts + tsconfig.json), an AGENTS.md guide, and — for tools — a generated declarations.ts. Prints the run + git push next steps.

uraijs init my-tool                 # a tool in ./my-tool
uraijs init flows --type workflow
uraijs init utils --type library

The inner loop

uraijs dev [script] [--call <fn> -a <json>]

Watch the sources; on save, reload and re-run — regenerates declarations.ts and either re-runs --call <fn> or lists the tools. --interval-ms tunes polling.

uraijs call <script> <fn> -a '<json>'

Run one tool function once. Accepts -d/--work-dir, secrets/vars (see below). The result JSON is the stdout payload.

uraijs list-tools <script>

Print the tool declarations. --json emits the raw declarations array.

uraijs schema [script] [--stdout] [--force]

Regenerate declarations.ts from the tool source (local codegen — the offline equivalent of server-side schema generation). --stdout prints instead of writing; declarations.ts is generated and versioned but hand-editable, so a write refuses to clobber a hand-edited file without --force.

uraijs test [script]

Run *.urai-test.json fixtures — an array of cases:

[
  { "fn": "greet", "args": { "name": "Ada" }, "expect": "Hello, Ada!" },
  { "fn": "charge", "args": { "amount": -1 }, "expectError": true }
]

expect deep-equals the result; expectError: true passes iff the call throws. Exits non-zero on any failure (a CI gate). --json emits a report. With no fixtures it runs demo probes and exits 0.

Types, secrets, libraries

uraijs types

Write/refresh urai.d.ts + tsconfig.json so the TypeScript language server understands the tool globals, decorators, and urai:* imports.

uraijs secrets detect [script]

List the secret names the code references (meta.secrets.X and secrets.get("X")). See secrets.md for the full model.

uraijs lib link <org>/<name> <path> · unlink · list

Point a urai:lib/<org>/<name> import at a local checkout during development (writes [lib."<org>/<name>"] to urai.toml), so you can develop a tool and its libraries together offline.

uraijs lib link acme/billing ../billing-lib
uraijs lib list

Workflows

uraijs workflow run <ClassName> -a '<json>' [--id <id>]

Drive a durable workflow to completion locally, persisting state + completed steps to .urai/workflows.json. Reuse --id to resume an interrupted run — completed steps are memoized and not re-run. --script, --store, -d, and secrets/vars are accepted.

uraijs workflow run MyWorkflow -a '{"q":"hello"}'    # prints the instance id
uraijs workflow run MyWorkflow --id <id>             # resume
uraijs workflow list

One-shot scripts

uraijs eval <file.ts> (alias: uraijs run)

Run an arbitrary one-shot script in a fresh sandbox — the script must call urai.complete(value). Flags: --timeout-ms, --heap-mb, --allow-host <host> (repeatable), plus secrets/vars.

uraijs run job.ts -s '{"API_KEY":"…"}'

Secrets & variables (all run commands)

-s/--secrets '<json>', --secrets-file <path>, -v/--vars '<json>', --vars-file <path>; plus env vars and [run] defaults in urai.toml. Precedence and the two in-code access forms are documented in secrets.md.

urai.toml

The project manifest, discovered by walking up from the current directory:

[project]
name = "my-tool"
type = "tool"          # tool | workflow | library
main = "tool.ts"

# Point urai:lib imports at local checkouts during dev:
[lib."acme/billing"]
path = "../billing-lib"

[run]
secrets_file = ".secrets.json"
vars_file    = ".vars.json"
env_secrets  = ["OPENAI_API_KEY", "TWILIO_*"]