This page describes the first version of the package. For version 0.3, with every studio, API keys and price approval, see the new setup guide.

The yesilcam-studios npm package gives you two commands. yesilcam is the command-line interface: everything you click in the app, you can run from a shell, with JSON output for the next tool in the chain. yesilcam-mcp is a Model Context Protocol server that lets Claude operate the studios as tools. Both use your normal account and your normal credit wallet, so a script and a colleague in the app never collide: they share the same queue and the same balance. This guide covers installation, sign-in, the main commands, the MCP setup and the habits that keep automation safe.

Install and sign in

  1. Install globally: npm install -g yesilcam-studios.
  2. Sign in once: yesilcam login. It asks for your account credentials and stores an access token.
  3. Check it worked: yesilcam balance prints your credit balance.

The token is saved to ~/.config/yesilcam/config.json with owner-only file permissions. Run yesilcam logout to remove it, for example before handing over a machine. The token grants full access to the account, including spending credits, so treat it like a password: do not commit it, do not paste it into shared chats, and replace it by logging out and in again if it may have leaked.

Generate from the terminal

  • yesilcam image "a lighthouse at dusk, 35mm film" --tier standard --out lighthouse.png creates an image on the standard tier and saves it.
  • yesilcam video --from 1234 --duration 5 --wait starts a five-second clip from image 1234 and waits for it to finish.
  • yesilcam tryon --garment 88 --person 77 --out look.png runs a try-on with a garment asset and a model.
  • yesilcam maket analyze plan.dxf reads a floor plan and reports walls, doors, windows and rooms.
  • yesilcam maket create "Villa", yesilcam maket save ground.dxf --project 12 --floor 0 and yesilcam maket plans 12 mirror the project and plan model in the app.

Add --json to any command for machine-readable output; the ids it returns are what you feed to the next command. --wait blocks until the job finishes instead of returning at once with a job id. Every job costs exactly what it would cost in the app, with your plan multiplier applied, and failed jobs are refunded the same way.

Scripting patterns

  • A nightly catalog. Loop over a folder of garment photos: upload each with yesilcam --json assets upload, read the asset id, then run yesilcam --json tryon with --wait and --out. Forty garments become forty looks while you sleep.
  • Storyboards from a script. Split a screenplay into scene prompts and loop yesilcam image on the draft tier into a folder. Review the folder, then rerun only the keepers on standard.
  • Plan checks in CI. yesilcam maket analyze plan.dxf --json returns the detected walls, doors, windows and rooms. Fail the build if a plan has no rooms or its units had to be guessed.

One rule: run jobs one after another rather than in parallel when you need their ids in order. Parallel runs are fine for independent work, but a script that assumes job 2 was created after job 1 must submit them sequentially.

Connect Claude

The MCP server exposes the studios as tools: create image and video, run a try-on, check job status, list library assets, list characters, read the balance, quote prices, and analyze or save Maket plans. Setup takes two commands.

  1. Print your token: yesilcam login --json and copy the token field.
  2. Register the server with Claude Code: claude mcp add yesilcam -e YESILCAM_TOKEN=<token> -- yesilcam-mcp.

Claude Desktop reads the same server from its configuration file; yesilcam mcp prints the snippet to paste there. Once connected, you describe the outcome and Claude sequences the calls: "Storyboard these six scenes on draft, show me the frames, then produce the two I pick on standard." It creates the jobs, waits, returns the URLs, and, because the pricing tool is available, can quote a cost before committing.

Keeping a human in the loop

Draft work can be autonomous. Standard and cinema production should wait for your explicit yes, because that is where the credits go. Say so in your instructions ("ask before any job above draft") and Claude will ask. The same applies to scripts: put the tier in a variable, default it to draft, and make the higher tiers an explicit flag. Check the balance before a long batch, and remember that the wallet is shared with the app, so a colleague producing a film at the same time draws from the same credits.

Troubleshooting

  • Command not found. The directory where npm puts global binaries is not on your PATH. Add it and open a new shell.
  • Unauthorised. The stored token was removed, or the config file was deleted. Run yesilcam login again.
  • The MCP server does not appear. The environment variable name is YESILCAM_TOKEN and the value is the token from yesilcam login --json, not your password. Restart the client after adding the server.
  • A job returns no output. Check its status; a failed job is refunded and can be resubmitted.

Frequently asked

Does the CLI cost extra? No. It uses the same credit wallet and the same prices as the app.

Where is the token stored? In ~/.config/yesilcam/config.json, readable only by your user. yesilcam logout deletes it.

Can Claude spend credits without asking? Only if you let it. Every tool reports the job and its status, the pricing tool lets it quote first, and an instruction to ask before non-draft tiers is respected.

Can I use the CLI and the app at the same time? Yes. Jobs from both appear in the same queue and the same Library.